Pull Requests and Code Review with the GitHub CLI

You will open a pull request from the command line, run reviews, and merge only after checks pass. By the end you will have a review workflow and branch protection that keeps unreviewed code out of main.

A pull request is more than a merge button: it is the checkpoint where code gets read by a second pair of eyes, where CI proves the change builds and passes tests, and where the reasoning behind the change is recorded for future you. Doing the whole flow with the gh CLI means you never leave the terminal, and every stage, opening, reviewing, checking status, merging, is scriptable and repeatable. That repeatability is what turns "we should review code" into a process a team can actually rely on.

Architecture Overview

The diagram shows the merge gate. A feature branch becomes a pull request with gh pr create. Two independent signals then feed the merge decision: the required status checks (CI) must be green, and at least one reviewer must approve. Only when both are true does branch protection allow the merge, through the web button or gh pr merge, to land the change on main. If either signal is missing, the merge is refused no matter how convincing the branch looks locally.

This matters because it removes "it worked on my machine" from the equation. The checks run on a clean runner with a fresh checkout, and the approval comes from a human who is not the author. Branch protection enforces both at the repository level, so the rule holds even if someone tries to push directly to main or merge with the web UI at 2 a.m.

The lab walks the loop in five moves: prepare a branch (step 00), open the PR (step 01), review and wait on checks (step 02), merge (step 03), then lock the gate with branch protection (step 04).

How It Works

Environment Setup

You will need: the gh CLI authenticated (gh auth login) and a repo.

Before you begin: enable branch protection on main in repo settings.

Install gh if you do not have it, then confirm you are authenticated against the right account and host. The status output also prints the token scopes, you need the repo scope for private repositories and workflow if your PRs touch GitHub Actions files.

INSTALL AND AUTHENTICATE gh

# macOS
brew install gh

# authenticate against github.com (browser flow is easiest)
gh auth login --hostname github.com --git-protocol https --web

# verify
gh auth status

Common mistake: authenticating with one GitHub account while the repo belongs to another. gh auth status shows the active account for each host; switch with gh auth switch if you have more than one.

Work from a local clone so gh can infer the repository from your git remote. Every gh pr command below assumes you run it inside the clone; otherwise you must pass --repo owner/name to each call.

CLONE THE REPO

gh repo clone TYFSADIK/demo-api
cd demo-api
git remote -v   # origin must point at the GitHub repo

How to verify: gh repo view --json name,owner should print the repo you expect. If it errors with "not a git repository", you are in the wrong directory.

Step-by-Step Execution

git checkout -b feature/api
# ...make your changes...
git add -A
git commit -m "Add /health endpoint"
git push -u origin feature/api

gh pr create --base main --head feature/api \
  --title "Add /health endpoint for uptime checks" \
  --body-file .github/pull_request.md

# .github/pull_request.md
## What
Adds GET /health returning { "status": "ok" }.
## Why
The load balancer needs a lightweight liveness probe. Closes #17.
## How tested
curl localhost:8080/health locally + a new pytest case.

gh pr status            # PRs for your branches: review state, checks
gh pr view 42           # title, body, reviewers, check rollup

gh pr edit 42 --add-reviewer alice,team-leads
gh pr diff 42               # full diff, paginated
gh pr view 42 --comments    # discussion so far

gh pr review 42 --approve --body "LGTM - probe returns 200 in 3ms"
gh pr review 42 --request-changes --body "Handle the DB-down case before merge"
gh pr review 42 --comment --body "Question: why not reuse readiness.py?"

git checkout feature/api
# ...address the review comments...
git commit -am "Handle DB-down case in /health"
git push                    # PR #42 picks up the new commit automatically
gh pr checks 42 --watch     # confirm CI re-runs and goes green

git checkout main
git pull --prune            # fetch the squash commit, prune deleted remote branches

gh api repos/TYFSADIK/demo-api/branches/main/protection -X PUT \
  --input - <<'EOF'
{
  "required_status_checks": {
    "strict": true,
    "contexts": ["test"]
  },
  "enforce_admins": true,
  "required_pull_request_reviews": {
    "required_approving_review_count": 1,
    "dismiss_stale_reviews": true
  },
  "restrictions": null
}
EOF

gh api repos/TYFSADIK/demo-api/branches/main/protection \
  --jq '.required_pull_request_reviews.required_approving_review_count,
        .required_status_checks.strict,
        .enforce_admins.enabled'

Progress So Far

The three core moves, open, review, merge, are the loop you will run dozens of times a week. Steps 00 and 04 bookend it: a well-prepared branch makes the PR easy to review, and branch protection makes the loop mandatory rather than optional.

Anatomy of a Good PR

Reviewers decide how carefully to read based on signals you control. A PR that gets a fast, useful review usually has all of these:

• Small diff: under ~400 lines changed. Bigger than that and reviewers skim; split large work into stacked PRs.
• Single purpose: one feature or one fix. "Add endpoint + refactor logging + bump deps" forces the reviewer to hold three conversations at once.
• A body that answers what / why / how-tested, the template from step 01.
• Green checks before review is requested: asking a human to read code CI has already rejected wastes the most expensive resource in the loop.
• Linked issue: Closes #17 ties the change to the reason it exists and auto-closes the ticket on merge.

The inverse is also a skill: as a reviewer, a PR missing these signals is itself feedback. Ask for a split or a better description before diving into the diff, that is a legitimate --comment review.

Draft PRs and Work in Progress

Open a PR as a draft when you want CI feedback and early eyes but the change is not ready to merge. Drafts cannot be merged, which makes them a safe way to share half-finished work without risking an accidental merge:

DRAFT PR WORKFLOW

gh pr create --draft --title "WIP: caching layer" --body "Early feedback welcome"
# ...keep pushing commits; CI runs on every push...
gh pr ready                 # flip to ready-for-review when done
gh pr ready --undo          # back to draft if review uncovers big problems

Drafts are also the answer to "how do I run CI without merging": the checks run on every push to the PR branch whether or not the PR is a draft, so you get the full pipeline signal long before a reviewer is involved.

Keeping a PR Up to Date with main

PRs age. While yours waits for review, main moves, and with strict=true in branch protection you must be current before merging. Two ways to catch up, both ending in a force-free push:

UPDATE THE PR BRANCH

# option A: merge main in (keeps history, adds a merge commit)
git checkout feature/api
git fetch origin
git merge origin/main
git push

# option B: rebase onto main (linear, but rewrites the branch)
git fetch origin
git rebase origin/main
git push --force-with-lease

Prefer merge on shared branches and rebase on branches only you touch; --force-with-lease (never plain --force) refuses to overwrite commits someone else pushed since your last fetch. Either way, expect CI to re-run and, with dismiss_stale_reviews on, expect to ask for a re-approval.

How to verify: mergeable reports MERGEABLE and the approval count is back above your required threshold before you reach for gh pr merge.

The Reviewer's Side

Reviews are easier to do well when you can run the code, not just read it. gh can check out any PR into a local branch in one command, so you can run the tests, poke the endpoint, and then leave your verdict:

CHECK OUT AND TEST A PR LOCALLY

gh pr checkout 42           # fetch PR head into a local branch
pip install -r requirements.txt
pytest -q                   # run the suite against the proposed change
curl -s localhost:8080/health   # manual smoke test

When you are done, git checkout main drops you back; the PR branch is disposable. Review the behavior first, the diff second, a change that reads beautifully but breaks the smoke test still gets --request-changes.

Review etiquette worth adopting early: comment on the code, not the author ("this branch dereferences null" beats "you broke this"); distinguish blockers from nits explicitly (nit: prefix means "optional, your call"); and respond to every review comment, even if only with "done in 3f2a1b9", silence forces the reviewer to re-read the diff to find out what changed.

Testing & Validation

You should see the merged PR and the squashed commit on main. With protection on, an unreviewed or failing PR cannot merge.

FULL VALIDATION SWEEP

gh pr list --state merged --limit 5 --json number,title,mergedAt \
  --jq '.[] | "#\(.number) \(.title) - \(.mergedAt)"'
git log main --oneline -3
gh api repos/TYFSADIK/demo-api/branches/main/protection --jq '.enforce_admins.enabled'

For a negative test, push a branch with a deliberately failing test and open a PR. The merge command must refuse. If it does not, your protection rule or required check context is wrong, revisit step 04.

Finally, confirm the audit trail is intact: the PR page should show the full conversation, the approving review, the green check rollup, and the squash commit linking back to the PR number. That trail is what you will dig through six months from now when the endpoint misbehaves, if it is all there, the lab is done.

gh PR Command Cheat Sheet

The commands from this lab, collected for reference. Everything assumes you are inside the repo clone; add --repo owner/name to run them from anywhere:

EVERYDAY gh PR COMMANDS

gh pr create --base main --fill          # open PR, reuse commit messages
gh pr status                             # your PRs + review/check state
gh pr list --state open                  # everything waiting on someone
gh pr view 42 --web                      # open in browser
gh pr diff 42                            # read the patch
gh pr checkout 42                        # run it locally
gh pr checks 42 --watch                  # follow CI until it finishes
gh pr review 42 --approve                # or --request-changes / --comment
gh pr merge 42 --squash --delete-branch  # merge + tidy up
gh pr ready 42                           # flip a draft to ready-for-review

Troubleshooting

Extension Ideas

• Add automated checks in GitHub Actions so the required check has something real to run.
• Require CODEOWNERS review for sensitive paths, a CODEOWNERS file routes PRs touching /infra/ or auth code to specific reviewers automatically.
• Auto-merge once checks pass with gh pr merge --auto, so approved PRs land the moment CI goes green without anyone babysitting the queue.
• Adopt a PR template (.github/pull_request_template.md) so every body starts with the what/why/how-tested structure from step 01.

Practice Challenges

Key Results

• Opened and merged a PR entirely from the CLI.
• Enforced review approval before merge.
• Required passing checks via branch protection.
• Kept main clean with squash + branch deletion.