GitHub Commands & Workflow Guide

The Complete Guide to GitHub Collaboration

GitHub has become the de facto platform for software collaboration, hosting over 100 million repositories and serving as the home for virtually every major open-source project. While Git is the version control system, GitHub adds a social and collaborative layer on top—pull requests, issues, code review, project management, and more. Understanding GitHub workflows is essential for any developer participating in team projects or open-source communities.

This guide focuses on the workflows and commands specific to GitHub collaboration, particularly the patterns used for contributing to projects where you do not have direct write access. These same patterns apply whether you are making your first open-source contribution or working across teams within a large organization.

Understanding Forks and Pull Requests

The fork-and-pull model is GitHub's solution to open-source collaboration at scale. When you fork a repository, GitHub creates a complete copy under your account. You have full permissions on your fork—you can create branches, push commits, and experiment freely without affecting the original project.

When you are ready to contribute your changes back, you open a Pull Request (PR). This is a formal request asking the maintainers of the original repository to "pull" your changes into their codebase. Pull requests are not just about code—they are a communication tool. They provide a space for discussion, code review, and iterative refinement before changes are merged.

The PR page shows the commits you are proposing, a diff of all changes, and a discussion thread. Reviewers can comment on specific lines of code, request changes, or approve the PR. GitHub displays the status of any automated checks (tests, linting, security scans) configured by the project.

The Upstream and Origin Convention

When working with forks, you typically have two remotes. "Origin" points to your fork—this is where you push your work. "Upstream" points to the original repository—this is where you fetch updates from.

Setting up the upstream remote is crucial for keeping your fork synchronized. Open-source projects receive constant updates, and your fork can quickly become outdated. Before starting new work, always fetch from upstream and merge into your main branch. This ensures your feature branches start from the latest code.

The naming is just convention—you could call these remotes anything—but "origin" and "upstream" are so universally used that documentation and tutorials assume these names. Sticking to the convention makes it easier to follow guides and communicate with other developers.

Creating Effective Pull Requests

A well-crafted pull request significantly increases your chances of getting contributions accepted. Start with a clear, descriptive title that summarizes the change. Use the description to explain what the PR does, why it is needed, and any important context reviewers should know.

Many projects provide PR templates that guide you to include specific information. Follow these templates carefully—maintainers include them for good reasons. If a project has a CONTRIBUTING.md file, read it before submitting. It often explains coding standards, testing requirements, and the review process.

Keep PRs focused on a single change. A PR that fixes one bug is easier to review and more likely to be merged quickly than a PR that fixes three bugs and adds a feature. If you have multiple independent changes, submit them as separate PRs.

Before submitting, review your own changes. Look through the diff on GitHub as if you were the reviewer. You will often catch issues you missed while coding. Make sure tests pass, the build succeeds, and you have not included any debugging code or unrelated changes.

Code Review Etiquette

When receiving feedback on your PR, approach it with an open mind. Maintainers often have deep context about the codebase and its design decisions. Questions are not attacks—they are opportunities to learn and improve your contribution.

Respond to all review comments, even if just to acknowledge that you have made the requested change. If you disagree with feedback, explain your reasoning respectfully. Sometimes reviewers will reconsider; sometimes they will explain context that changes your mind.

When reviewing others' code, be constructive and specific. "This is wrong" is not helpful; "Consider using X here because Y" is. Distinguish between requirements (things that must change) and suggestions (nice-to-haves). Many teams use prefixes like "nit:" for minor suggestions.

The GitHub CLI

The GitHub CLI (gh) brings GitHub workflows to your terminal. Instead of switching to the browser to create a PR or check issue status, you can do it all from the command line. This is especially powerful when combined with shell scripting for automation.

Install it from cli.github.com and authenticate with gh auth login. The CLI supports most GitHub operations: cloning repos, creating and managing issues, creating and reviewing PRs, checking workflow runs, and more.

Some particularly useful commands: gh pr checkout 123 fetches and checks out a pull request locally for testing—much easier than the manual steps of adding someone's fork as a remote and checking out their branch. gh pr create walks you through creating a PR interactively, or use flags to script it.

GitHub Actions and CI/CD

Most active GitHub projects use GitHub Actions or other CI/CD systems to automatically test, build, and validate changes. When you open a PR, these workflows run automatically, and their status appears on the PR page.

If checks fail, investigate by clicking through to the workflow logs. Common failures include test failures (your code broke something), linting errors (style violations), and build failures. Many projects require all checks to pass before merging.

You can trigger workflows to re-run by pushing new commits to your branch. Some projects allow maintainers to re-run workflows via the GitHub UI, useful when failures are due to flaky tests or infrastructure issues rather than your code.

Managing Branches and Cleanup

After a PR is merged, you should delete the feature branch—both locally and on your fork. GitHub often offers a button to delete the branch after merging. Locally, run git branch -d feature-name to delete merged branches.

Over time, your local repo accumulates references to remote branches that no longer exist. git fetch --prune cleans these up. You can make this automatic with git config --global fetch.prune true.

Periodically sync your fork's main branch with upstream and prune stale branches. A clean repository with a clear structure is easier to work with and less likely to cause confusion.

SSH vs HTTPS Authentication

GitHub supports both SSH and HTTPS for repository access. HTTPS is simpler to set up but requires entering credentials (or using a credential helper). SSH uses key pairs and, once configured, allows passwordless operations.

To use SSH, generate a key pair with ssh-keygen, add the public key to your GitHub account, and clone repositories using the SSH URL (git@github.com:user/repo.git instead of https://...). The GitHub CLI can also help configure authentication.

Best Practices for Open Source

When contributing to open source, respect the maintainers' time. Before opening an issue or PR, search existing issues to see if it has been discussed. For new features, consider opening an issue first to discuss the approach before investing time in implementation.

Be patient. Maintainers are often volunteers with limited time. If your PR sits for a while, a polite ping is acceptable, but demanding immediate attention is not. Building a reputation through quality contributions over time is more valuable than any single PR.

Start small. Your first contribution to a project should probably be a documentation fix, a simple bug fix, or an improvement to tests. This helps you learn the project's workflow and build trust with maintainers before tackling larger changes.