Pull request approvals — N approvals, CODEOWNERS, dismiss stale, the audit

LVII-03 covered the deploy-side gate: the protected environment that holds the deploy job until reviewers approve. This lesson covers the change-side gate: the pull request that holds the change until reviewers approve. The two gates address different categories of failure and compose into a single discipline. The PR gate approves the change; the environment gate approves the deployment.

What a PR approval is

A pull request approval is a reviewer marking the change as ready to merge. The mark is recorded in the PR’s audit trail.

gh pr review 123 --approve --body "Migration reviewed; safe for production."

The approval is recorded; the merge button becomes enabled if all other requirements are met.

flowchart LR
    A["PR opened"] --> B{"N approvals?"}
    B -- "no" --> C["Merge blocked"]
    C --> B
    B -- "yes" --> D{"CODEOWNERS satisfied?"}
    D -- "no" --> C
    D -- "yes" --> E{"Required checks green?"}
    E -- "no" --> C
    E -- "yes" --> F["Merge enabled"]

The three conditions compose: N approvals, CODEOWNERS approvals, and required CI checks. The merge requires all three.

N approvals and the audit trail

The N-approvals rule sets the minimum number of approving reviews. N=2 is the common minimum for infrastructure repositories; regulated environments may require N=3 or higher.

The audit trail each PR produces is the link between the production deploy and the change. It records reviewer, timestamp, comment, and commit SHA. It is permanent.

gh pr view 123 --json reviews,commits,comments

The view subcommand returns reviews with state, commits, and comments. The source of truth for who approved what, when, and why.

CODEOWNERS as the per-path requirement

CODEOWNERS is the per-path requirement on top of the N-approvals rule. N-approvals asks do enough reviewers approve?; CODEOWNERS asks did a reviewer who owns this path approve?. The two compose.

ls .github/CODEOWNERS
cat .github/CODEOWNERS

The file maps paths to reviewers, read by the forge at PR open time. The requirement is enforced only if branch protection has Require review from Code Owners enabled.

Dismiss-stale and the audit trail

Dismiss-stale revokes a previous approval when new commits are pushed to the PR. An approval was made against the diff at commit X; new commits change the diff; the approval no longer applies. Without dismiss-stale, an engineer could approve a PR early, push unrelated changes, and merge with an approval covering a different diff.

gh pr view 123 --json reviews

The output shows dismiss-stale state. An approval listed as dismissed: true was invalidated by a subsequent push. The trade-off: dismiss-stale slows PRs because every push re-opens the review. Push commits in logical units.

How the two gates compose

The PR gate approves the change; the environment gate approves the deployment. They address different risks:

• PR gate. Did reviewers who understand the code review the change? Did the diff pass automated checks?
• Environment gate. Is this deployment safe given the current state of production?

The PR gate fails when the change is wrong; the environment gate fails when the deployment is wrong. A PR passing review but applied at the wrong moment is caught by the environment gate. A PR applied at the right moment but with a code bug is caught by the PR gate.

The audit trail is the composition: PR record links change to reviewers; environment record links deploy to context.

Production discipline

1. The PR gate approves the change; the environment gate approves the deployment. Two audits, two records.
2. N approvals is the minimum, not the maximum. N=2 is the common floor; regulated environments go higher.
3. CODEOWNERS required review must be enabled in branch protection - the file alone does not enforce the gate.
4. Dismiss-stale invalidates approvals on new pushes. Push commits in logical units.

Cross-course references

• This course, Part LVII-03 (Protected environments) covers the deploy-side counterpart.
• This course, Part XXXI-04 (CODEOWNERS required reviews) covers the wiring between the file and branch protection.
• This course, Part XXXII-03 (Required approvals and status checks) covers the composition of the three merge conditions.

Quiz