Skip to content

GitHub PR Review Architecture

Jump to bottom
amirbena edited this page Oct 15, 2026 · 4 revisions

GitHub PR Review Architecture

This page shows how github-pr-review is built: how a review of a Pull Request flows from invocation to an optional publication, and what makes this mode different. For how to use it, see GitHub-PR-Review-Guide. Back to Architecture-Overview.

github-pr-review is an adapter over the Shared-Review-Engine. It acquires a PR as the Review Target and hands it to the engine, as the local adapter does. It then adds a layer the local adapter does not need: deciding whether, and under whose authority, anything may be written back to GitHub.

The flow

sequenceDiagram
    actor U as Caller
    participant S as github-pr-review
    participant GH as GitHub
    participant E as Shared engine
    participant A as Authorization gate

    U->>S: PR + requested mode (default PASSIVE)
    S->>GH: identity, authority, PR metadata
    S->>GH: reviewed SHA (HEAD) + full paginated PR scope
    opt repository-backed checkout requested
        S->>GH: isolated, read-only checkout at the reviewed SHA
    end
    S->>E: Review Target + context + prior-review evidence
    E-->>S: findings + Decision
    S-->>U: Reviewer Brief (private)
    S->>GH: confirm HEAD has not moved
    S->>A: mode, independence, permission, current HEAD
    alt authorized and HEAD unchanged
        A->>GH: publish review (and optional status)
    else not authorized, preview-only, or stale
        A-->>U: report only, with the reason
    end
Loading

What is specific to GitHub mode

Reviewed-SHA binding and stale-HEAD protection. The review is tied to the exact commit (HEAD) that was reviewed. HEAD is re-checked before anything is submitted; if the PR moved, nothing is published and the review is treated as stale, so a verdict is never attached to code it did not examine.

Review authority. The Skill resolves who is reviewing and whether they may act. Self-review is allowed — the analysis runs in full and a verdict is reported — but no formal APPROVE / REQUEST_CHANGES event is ever submitted on one's own work (an informational COMMENT may be). This holds for the author's alternate accounts, bots, GitHub Apps, and nested agents too: reviewer independence is authority separation, not a different username.

PASSIVE / SEMI / ACTIVE. Publication is a separate decision from analysis:

Mode Behavior
PASSIVE (default) Return a report; write nothing to GitHub
SEMI Show what would be published; write nothing
ACTIVE Publish, if self-review, independence, permission, and HEAD checks all pass

An explicit ACTIVE request is itself sufficient authorization to publish: no second activation phrase or out-of-band signal is needed. The self-review boundary, reviewer independence, GitHub permission, and HEAD freshness still apply. An unclear request fails closed to not publishing. A verdict is not itself a GitHub event, and approving a PR is not authority to merge. See Feature-GitHub-Publication-and-Authorization.

Prior-review evidence. Earlier reviews and comments on the PR are classified (still relevant, resolved, stale, duplicate, settled, speculative) and used as evidence. When prior reviewed state exists, a re-review can be limited to what changed since. See Feature-Delta-Re-Review. A PR whose base is another open PR is treated as one layer of a stack, scoped to its own changes; the lower stack is read-only context.

Optional checkout. The Skill can materialize an isolated, read-only checkout at the reviewed SHA for deeper context. It is context only: no code from the PR is executed, and the checkout is removed on every exit path. If it fails, an optional checkout degrades visibly to API-only; a required one yields REVIEW INCOMPLETE.

Parallel workers (optional). Independent review dimensions may run as read-only workers over the same snapshot, only when the runtime reliably supports it; sequential review is always the fallback and must reach the same findings and decision. Workers return candidate findings only and hold no publication authority; one aggregator reconciles them and derives the single decision. A missing required dimension yields REVIEW INCOMPLETE, never REVIEW CLEAN.

Reviewer Brief. A private summary for the human caller, composed after the findings and decision are final. It is never an input to the GitHub review, so it cannot reach GitHub.

Publication boundary. The GitHub review body and inline comments are built only from their own templates, then pass through the authorization gate. An optional machine-readable status can be published for the exact reviewed SHA. See Feature-GitHub-Merge-Enforcement.

Where it joins the shared engine

The Review Target, context, and prior evidence enter the same engine as in local mode, and the same severity, coverage, and mechanical decision come out: REVIEW CLEAN, CHANGES REQUIRED, or REVIEW INCOMPLETE in both modes. What differs is delivery: here a clean result may become a submitted APPROVE and a blocking one a REQUEST_CHANGES event, only when ACTIVE publication and every guard above allow it. A withheld event is reported with its reason, and a clean result with a withheld approval is never reported as "approved".

Canonical references

See also

Home

Start here

Use the Skills

How reviews work

Architecture

Contribute

Background

Clone this wiki locally