Lesson 11 intermediate

GitHub Workflow with Git

The everyday pull request flow from issue to merge: branch, commit, push, open a pull request with the gh CLI, review and update it, keep it current, merge options, branch protection and CI checks, forks for outside contributors and how the same flow works on GitLab.

Git records history; a hosting service turns it into teamwork. On GitHub the unit of collaboration is the pull request (PR): a request to merge one branch into another, with a place to discuss, review and run automated checks before anything reaches main. GitLab calls the same thing a merge request (MR). This lesson walks one Orbit change through the whole flow.

The flow at a glance

  1. Start from an issue that describes the change.
  2. Update main and create a branch.
  3. Commit in small steps and push the branch.
  4. Open a pull request.
  5. CI runs and teammates review.
  6. Push more commits to address feedback.
  7. Merge, delete the branch, pull main.

The same seven steps hold for a one-line fix and a three-week feature. Only the size of the review changes.

Start from fresh main

$ git switch main
$ git pull --ff-only
$ git switch -c fix/ORB-142-login-timeout

Branching from an up-to-date main keeps the pull request small and conflict-free. Including the issue number in the branch name lets many tools link the two automatically.

Commit and push

$ git commit -am "Raise login timeout to 30 seconds"
$ git commit -am "Log the timeout value at startup"
$ git push -u origin fix/ORB-142-login-timeout
remote: Create a pull request for 'fix/ORB-142-login-timeout' on GitHub by visiting:
remote:      https://github.com/orbit-dev/orbit/pull/new/fix/ORB-142-login-timeout

Git prints a link to open the pull request in the browser. You can also do it from the terminal.

Open the pull request with gh

The GitHub CLI, gh, handles pull requests without leaving the terminal. Install it (winget install GitHub.cli, brew install gh or your Linux package manager) and log in once with gh auth login.

$ gh pr create --base main --title "Raise login timeout to 30 seconds" \
    --body "Fixes #142. Slow mobile networks hit the 10 s limit during peak hours."
https://github.com/orbit-dev/orbit/pull/87
$ gh pr create --draft --fill        # draft PR, title and body from your commits

A draft pull request says “not ready yet, but have a look”. Reviewers are not requested until you mark it ready with gh pr ready.

A good pull request description answers three questions: what changes, why, and how to test it. Writing Fixes #142 closes the issue automatically when the PR merges.

Reviews and checks

When the PR opens, two things happen:

  • CI checks run: build, tests, linters, security scans. Their results appear at the bottom of the PR. On GitHub these are usually GitHub Actions workflows; the CI/CD Tutorial builds them for GitLab.
  • Reviewers read the diff and leave comments, then approve or request changes.
$ gh pr checks 87                    # check status
$ gh pr view 87 --comments           # read the discussion
$ gh pr review 87 --approve          # as a reviewer
$ gh pr checkout 91                  # check out someone else's PR locally to test it

As a reviewer, focus on correctness, security and clarity, not on style a linter could catch. As an author, keep PRs small: a 200-line PR gets a careful review; a 2,000-line PR gets a skim.

Updating the pull request

To address feedback, commit on the same branch and push. The PR updates itself:

$ git commit -am "Make timeout configurable through LOGIN_TIMEOUT"
$ git push

If main moved and the PR has conflicts or is out of date, bring main in:

$ git fetch origin
$ git rebase origin/main             # or: git merge origin/main
$ git push --force-with-lease        # needed after a rebase

If you clean up commits with an interactive rebase or git history, push with --force-with-lease too. Reviewers can still compare versions through the “compare” link GitHub adds after each force-push.

Merging

GitHub offers three merge buttons. Repository settings decide which are allowed:

OptionResult on mainGood for
Create a merge commitAll PR commits plus a merge commitKeeping the full story
Squash and mergeOne commit per PRClean, linear main; messy PR commits
Rebase and mergePR commits replayed, no merge commitLinear history with meaningful commits
$ gh pr merge 87 --squash --delete-branch
$ git switch main && git pull --ff-only
$ git branch --delete-merged 'origin/*'     # Git 2.56: remove merged local branches

Protecting main

In a team, nobody should push straight to main. Branch protection rules (or rulesets) on GitHub and protected branches on GitLab enforce the flow:

  • Require a pull request before merging, with at least one approval.
  • Require status checks (CI) to pass.
  • Require branches to be up to date before merging, or use a merge queue that tests PRs together.
  • Require signed commits (lesson 17) and linear history if your team wants them.
  • Block force pushes and deletion of main.

A CODEOWNERS file assigns reviewers automatically by path:

# .github/CODEOWNERS
/deploy/        @orbit-dev/platform
/api/           @orbit-dev/backend
*.tf            @orbit-dev/platform

Forks: contributing from outside

Without write access to a repository, you fork it: a copy under your account. You push branches to your fork and open the pull request against the original. Lesson 7 showed how to add the original as the upstream remote and keep your fork current. gh repo fork --clone does the fork, clone and remote setup in one command.

The same flow on GitLab

GitLab uses the same Git commands; only the vocabulary and the CLI differ:

GitHubGitLab
Pull requestMerge request
GitHub ActionsGitLab CI/CD
gh pr createglab mr create
Branch protection / rulesetsProtected branches, approval rules
CODEOWNERSCODEOWNERS (in Premium tiers)

GitLab also lets you create a merge request directly from the push with push options: git push -o merge_request.create -o merge_request.target=main.

Quick reference

TaskCommand
Start a changegit switch main && git pull --ff-only && git switch -c <branch>
Push the branchgit push -u origin <branch>
Open a PR / draft PRgh pr create / gh pr create --draft --fill
See checksgh pr checks <n>
Test someone’s PRgh pr checkout <n>
Update after rebasegit push --force-with-lease
Merge and clean upgh pr merge <n> --squash --delete-branch

Exercise

Your pull request has review comments asking for a change. How do you update it?

  1. Close the PR and open a new one with the fix
  2. Edit the files directly in the PR description
  3. Commit the change on the same branch and push; the PR updates automatically
  4. Merge the PR first, then fix it on main
Show answer

Answer: C. A pull request follows its branch. Every push to the branch shows up in the PR, keeping the discussion and the review history in one place.

Exercise

Your team wants exactly one commit on main per pull request, even when the branch has many small commits. Which merge option fits?

  1. Create a merge commit
  2. Squash and merge
  3. Rebase and merge
  4. Fast-forward only
Show answer

Answer: B. Squash and merge combines all the PR’s commits into one commit on main. Merge commits and rebase-and-merge keep every individual commit.

Exercise

A developer pushed directly to main and broke production, skipping review and CI. What prevents this in the future?

  1. A branch protection rule requiring pull requests with approvals and passing checks on main
  2. A .gitignore rule for main
  3. Asking everyone to use git pull –rebase
  4. Tagging every commit on main
Show answer

Answer: A. Branch protection (rulesets on GitHub, protected branches on GitLab) blocks direct pushes and only allows merging through reviewed pull requests whose CI checks pass.

Key takeaways

  • The pull request flow: fresh main, branch, small commits, push, PR, review and CI, update, merge, clean up.
  • gh (GitHub) and glab (GitLab) handle PRs and MRs from the terminal.
  • Address feedback by pushing to the same branch; after a rebase use --force-with-lease.
  • Choose merge commit, squash or rebase merges per repository, and protect main with required reviews and checks.
  • Forks let outsiders contribute; GitLab merge requests follow the same flow with different names.

FAQ

How big should a pull request be?

Small enough to review properly in one sitting, usually a few hundred lines at most. Split big features into a series of PRs, possibly stacked branches (lesson 6), or hide unfinished work behind a feature flag.

Should I rebase or merge main into my pull request branch?

Either works. Rebasing keeps the PR’s commits on top of current main and is common when the branch belongs to one person. Merging is safer when several people push to the same branch. Many teams let the hosting service do it with an “Update branch” button.

What is a draft pull request for?

Sharing early work, asking for direction or running CI without asking for a formal review. Mark it ready when you want reviewers to approve it.

What happens to my branch after the PR is merged?

On the server it is usually deleted automatically. Locally it stays until you delete it: git branch -d <branch>, or clean up all merged branches at once with git branch --delete-merged (Git 2.56) after a fetch with prune.

Do I need the gh CLI?

No. Everything works in the browser. gh saves time when you open many PRs, test teammates’ branches with gh pr checkout or script repository tasks.

↑ ↓ navigate Enter open Esc close