Code Review, Suggested Changes, CODEOWNERS, Review Requests, and Review Discipline: Concepts, Architecture, and Mental Model

1. The practical problem: “approved” is not a review operating model

Chapter 07 gave you a pull request as a change-control object. The next failure mode is organizational: teams add an approval button to the process but never define what approval means, who owns which paths, which feedback blocks merge, or what happens when new commits arrive. GitHub exposes several review signals; reliability comes from assigning each signal a precise meaning.

2. Comment, Approve, Request changes, and pending review

When reviewing Files changed, you may create line comments and keep them in a pending review. Those comments are not yet submitted to the author as a finished review. On submission, GitHub gives the review one of three dispositions: Comment records feedback without approval semantics; Approve states that the reviewer accepts the proposed changes; Request changes records that the reviewer believes changes are required before integration. Repository policy determines whether approval or a change request becomes a merge gate.

3. Review conversations and resolution are workflow state

An inline review comment starts a discussion thread tied to a file/line context. Replies create a conversation. Marking that conversation resolved is bookkeeping: it says the team considers the thread addressed or acknowledged. A ruleset or branch-protection rule can require all conversations to be resolved before merge, but resolution itself does not execute tests, prove correctness, or remove the historical discussion.

4. Review requests, teams, and CODEOWNERS are different layers

flowchart TD
  PR["PR head OID"] --> DIFF["Changed paths"]
  BASE["CODEOWNERS on base branch"] --> MATCH["Path matching"]
  DIFF --> MATCH
  MATCH --> RR["Automatic review request"]
  MAN["Manual request"] --> RR
  RR --> HUMAN["Human reviewer"]
  HUMAN --> REV["Review state"]
  POLICY["Branch protection / ruleset"] --> GATE["Merge gate"]
  REV --> GATE
  CHECKS["Automated checks"] --> GATE

A review request is routing: GitHub asks a user or team to look at the PR. A CODEOWNERS file is repository content that maps path patterns to users or visible organization teams. When a ready PR changes owned paths, GitHub can request those owners automatically. A required code-owner review is enforcement configured by branch protection or a ruleset. Routing and enforcement are related but not identical.

For CODEOWNERS to route correctly, GitHub reads the file from the base branch of the PR. Supported locations are .github/CODEOWNERS, CODEOWNERS at repository root, or docs/CODEOWNERS, searched in that order. Owners must have write access; organization teams must be visible and have write access.

5. CODEOWNERS matching is policy code: order, case, and unsupported syntax matter

CODEOWNERS resembles .gitignore, but it is not identical. The last matching pattern takes precedence. Paths are case-sensitive. Negation with ! and character ranges such as [a-z] are not supported. Invalid lines are skipped, and GitHub exposes CODEOWNERS syntax errors through the UI and REST API. This makes the file testable policy rather than magic text.

# Default ownership first
*                         @octo-owner

# Later matches take precedence
/docs/                    @octo-docs
/services/payments/       @octo-payments
/.github/CODEOWNERS       @octo-owner

6. Suggested changes are proposals that can become commits

A reviewer can attach a suggested change to an inline comment. The suggestion is not automatically correct and does not modify Git until it is applied. A person with write access can apply a suggestion directly; multiple suggestions can be batched into one commit. GitHub records the suggesters as co-authors and the person applying the suggestion as a co-author/committer. Because applying a suggestion moves the PR head, it can affect review freshness and checks.

The retry interval should remain bounded.

```suggestion
const MAX_RETRY_SECONDS = 30;
```

7. Review freshness: new commits can change what an approval means

An approval refers to what the reviewer actually saw. GitHub offers two important policy strategies. Dismiss stale pull request approvals when new commits are pushed invalidates approvals when relevant new commits or merge-base changes affect the reviewed diff. Require approval of the most recent reviewable push preserves earlier approvals but requires at least one authorized reviewer other than the latest pusher to approve the newest push. These are not synonyms; they encode different risk/throughput tradeoffs.

8. Human review and automated checks answer different questions

Human reviewers reason about intent, architecture, maintainability, threat boundaries, failure behavior, and whether the change belongs in the system. Automated checks execute repeatable validations such as tests, linting, policy checks, or security analysis. Neither replaces the other. A green CI suite cannot prove the design is correct; a senior reviewer cannot prove every test matrix passed. Later security chapters deepen scanning evidence, but this chapter teaches the interface: treat each result as one evidence source.

9. Read-only inspection before changing review state

# Structured PR state: no review mutation.
gh pr view 42 -R OWNER/REPO --json   number,title,isDraft,headRefOid,reviewDecision,reviewRequests,latestReviews,statusCheckRollup,url

# Current submitted reviews through versioned REST.
gh api   -H "Accept: application/vnd.github+json"   -H "X-GitHub-Api-Version: 2026-03-10"   "repos/OWNER/REPO/pulls/42/reviews"   --jq '.[] | {id,user:.user.login,state,commit_id,submitted_at}'

# Requested reviewers are a separate API object.
gh api   -H "Accept: application/vnd.github+json"   -H "X-GitHub-Api-Version: 2026-03-10"   "repos/OWNER/REPO/pulls/42/requested_reviewers"   --jq '{users:[.users[].login],teams:[.teams[].slug]}'

# CODEOWNERS parser evidence for the base/default branch.
gh api   -H "Accept: application/vnd.github+json"   -H "X-GitHub-Api-Version: 2026-03-10"   "repos/OWNER/REPO/codeowners/errors"   --jq '.errors'

The review REST response includes the commit_id associated with a submitted review. That field is useful evidence when asking whether a later head OID has moved beyond what a reviewer saw.

10. DevOps connection: review quality is a reliability and security control

A production review system must route expertise to relevant changes, preserve an auditable decision trail, and prevent unreviewed material from silently inheriting old approval. CODEOWNERS can make ownership visible; rules can enforce selected approval semantics; checks can supply repeatable evidence. The system still depends on reviewers asking concrete questions and authors responding with code or evidence rather than ceremony.

11. Lesson summary

GitHub review has several independent pieces: comments and pending reviews, submitted dispositions, review requests, CODEOWNERS routing, optional required-owner enforcement, conversation resolution, suggestions that can create commits, and freshness policies. The useful mental model is “evidence attached to a moving PR head under explicit policy,” not “green approval badge.”

Knowledge check

Authoritative references

• About pull request reviews
• About code owners
• Incorporating feedback in your pull request
• Requesting a pull request review
• About protected branches
• Available rules for rulesets
• gh pr view
• REST API endpoints for pull request reviews
• REST API endpoints for review requests
• REST endpoint: list CODEOWNERS errors
• REST API versions