Pull request fundamentals — proposing, reviewing, merging

A pull request is a request to merge one branch into another, mediated by review. The branch proposing the change is the head; the branch that would receive it is the base. The PR is the unit of change — not the individual commit. Every policy, every CODEOWNERS gate, every audit question is anchored on the PR.

Head, base, and merge base

A PR is not a Git object. It is a server-side record pointing at two refs and the commits reachable from the head but not from the base. Open a PR from feature/login-v2 into main and the platform computes the merge base, the diff range, and the set of files changed. None of that exists until the PR is opened. The branches themselves are ordinary Git branches; what the PR adds is the conversation, the checks, and the audit metadata that turns a branch into a candidate for the trunk.

flowchart LR
    H["head: feature/login-v2"] --> C1["commit a"]
    C1 --> C2["commit b"]
    C2 --> C3["commit c"]
    B["base: main"] --> M["merge base"]
    M --> C1
    M --> D1["main commit"]
    D1 --> D2["main tip"]

The PR’s commits are exactly the ones reachable from the head but not from the merge base. The proposed merge advances main to a new commit with two parents.

BRANCH="feature/login-v2"
git push origin "$BRANCH"
gh pr create --base main --head "$BRANCH" \
  --title "feat(login): add v2 login path" \
  --body "Replaces the legacy login with v2 behind LOGIN_V2 flag."

The review-then-merge pattern

A PR moves through three states. Open — change proposed and under review. Merged — platform produced a merge event on the base ref. Closed — withdrawn or rejected. The merge commit carries the PR number, the approved reviewers, and the passing checks — metadata that makes the PR the audit unit. The conversation on the PR — comments, review state changes, force-pushes — is also preserved; an auditor can read the timeline of the change as it was prepared, reviewed, and landed.

Production discipline

1. The base ref is sacred. Direct commits to it bypass every policy. The base ref is read-only at the server; force-pushes to it are forbidden.
2. A PR is the unit of change. Three PRs’ worth of work is three PRs, not one. Combining them loses the per-change audit and the per-change rollback.
3. Open the PR early. A PR opened against an empty branch and updated is easier to review than a 2,000-line PR opened at the end.
4. Reference the PR in the merge commit. Most forges do this automatically; verify with git log --merges that the merge commits carry PR references and that those references resolve to the expected PR.

Cross-course references

• GitOps with Argo CD - Part IV (SyncPatterns): the merge commit as the sync trigger and how the controller reads it.
• CI/CD Pipeline Patterns - Part III (FastCI): the CI checks that gate the PR and the runtime budget they share.
• Terraform for Production Sysadmins - Part XI (PRWorkflows): the Terraform PR workflow including plan runs and module versioning.

Quiz