// docs · v1.x

Review a GitHub PR — remote pr

commitbrief remote pr reviews a GitHub pull request via the gh CLI, posts findings as inline comments, and submits an approve / comment / request-changes verdict.

Updated November 10, 2026

commitbrief remote pr <PR-ID> reviews a GitHub pull request and writes the result back to GitHub: each finding is posted as an inline review comment, and the review is submitted with a verdict — approve, comment, or request-changes. It drives your locally-installed gh CLI, so CommitBrief makes no HTTPS calls of its own; gh’s auth, host resolution, and cross-fork handling are all reused.

This is a user-driven tool you run from your terminal, not a hosted bot. For CI, the official GitHub Action wraps this same command.

Usage

commitbrief remote pr 42                       # PR #42 in the current repo
commitbrief remote pr CommitBrief/web#10       # cross-repo (owner/repo#N)
commitbrief remote pr https://github.com/CommitBrief/web/pull/10
commitbrief remote pr 42 --request-changes-on=high
commitbrief remote pr 42 --max-verdict=comment # never approve
commitbrief remote pr 42 --json > report.json  # post, and write a machine-readable report
commitbrief remote pr 42 --repo CommitBrief/web

<PR-ID> accepts any form gh understands: a number, owner/repo#N, or a full URL.

Flags

FlagDefaultEffect
--request-changes-on <sev>(unset)Opt in to a request-changes verdict at or above this severity. One of critical, high, medium, low (info is rejected). Without this flag the verdict is never request-changes — see The verdict. Ignored under --no-post.
--max-verdict <approve|comment>approveCap the verdict. With comment, CommitBrief never submits an approve: a PR with no findings, or only info findings, gets a comment review instead. approve (the default) is no cap. request-changes is rejected as a value; it is switched on by --request-changes-on, not capped. Requires v1.22.0 or later. See Never approve. Ignored under --no-post (noted).
--repo <owner/repo>(git context)Target repository. Overrides discovery from the current git remote; required when you are not inside the repo.
--no-postfalseReview the PR diff and render it locally — write nothing back to GitHub. See Read-only mode.
--since-last-reviewfalseReview only the commits added since CommitBrief’s last review of this PR. Falls back to a full review whenever that range cannot be determined safely. Requires v1.20.0 or later. See Incremental review. Ignored under --no-post (noted).

Inherited globals that apply: --provider / --model / --lang, --no-cache, --allow-secrets, --verbose / --quiet. --json (optionally with --output) also applies in posting mode and writes a machine-readable report. Under --no-post the local-render globals (--json, --markdown, --output, --copy, --compact, --cli, --fail-on) apply too.

Read-only mode (--no-post)

commitbrief remote pr <ID> --no-post uses the PR diff purely as a review source and renders to your terminal exactly like a local review — it writes nothing back to GitHub (no inline comments, no verdict). Use it to triage a PR, pipe findings into another tool, or review a PR with a CLI provider.

Because the output is local rather than GitHub, the flags that normal remote pr rejects all apply:

commitbrief remote pr 42 --no-post                 # cards in your terminal
commitbrief remote pr 42 --no-post --json | jq .
commitbrief remote pr 42 --no-post --output review.md
commitbrief remote pr 42 --no-post --cli gemini    # CLI provider, no API key
commitbrief remote pr 42 --no-post --fail-on=high  # exit-code gate
AspectPosting mode (default)--no-post
GitHub writesinline comments + verdictnone
OutputGitHub, plus the report with --jsonterminal (--json / --markdown / --output / --copy / --compact)
ProvidersAPI onlyAPI or CLI (--cli)
--fail-onignored (verdict replaces it)applies (exit code)
--request-changes-on / --max-verdictdrive the verdictignored (noted)
Self-PRblocked by GitHuballowed (nothing is submitted)
Cachenot usedused (diff-hash, like a local review)
Inline commitbrief-ignoreapplied before the syncapplied to the preview; the count shows in meta.suppressed

--with-context is not combined with --no-post (it would read your local working tree, which need not match the PR’s branch); it is noted-and-ignored if set. You still need gh installed and authenticated — the diff is fetched through it.

Re-running on the same PR

Requires v1.20.0 or later. remote pr is safe to run after every push: it syncs with the review threads it already left instead of posting the whole review again.

  • A finding that is still there is left alone. If the comment text is unchanged nothing is written; if the wording changed, the existing comment is edited in place.
  • A new finding is posted once, at its line.
  • A finding that disappeared has its thread resolved. That includes findings in a file you later added to .commitbriefignore: the file is no longer reviewed, so its open CommitBrief threads count as gone on the next run and are resolved.
  • A finding silenced by an inline commitbrief-ignore marker is treated the same way. Requires v1.21.0 or later. It is removed before the sync, so no comment is posted for it and its open thread is resolved on the next run. See Inline suppression.
  • A finding that comes back reopens the thread CommitBrief had resolved when the code is still where it was. If the code changed and the thread went outdated, the finding is posted as a new comment at its new line and the old thread stays closed.
  • Duplicates collapse. Findings that share one identity are posted as a single thread; the other occurrences are listed in the comment as Also at:.

The sync prints one summary line on stderr:

Synced: N posted · M updated · K unchanged · R resolved · Q replied · H held

replied counts the status replies described below; held counts threads left untouched because a person took over (see What it never touches).

Hidden markers

CommitBrief recognises its own comments by hidden HTML comments at the end of the text. They do not render on GitHub, and you should not delete them when you edit a comment or quote it:

  • Every inline comment ends with <!-- commitbrief:fp=… v=1 -->, which carries the finding’s fingerprint. CommitBrief may add attributes to it when it resolves or records a thread.
  • Every review that was not narrowed by a path filter ends with <!-- commitbrief:reviewed=… -->, the head commit the review covered. --since-last-review reads it.

A comment without the marker, written by someone else, or carrying an unknown marker version is never edited, resolved, or replied to. Comments posted by an older CommitBrief carry no marker, so after upgrading a finding can appear once more beside its old comment.

What it never touches

Only threads CommitBrief itself started are ever synced. Beyond that, a person’s decision stands:

  • A thread you resolved is not reopened or replied to.
  • A thread you reopen after CommitBrief resolved it, or after CommitBrief saw you resolve it, is held: CommitBrief never resolves it again. It stays open after the finding is fixed until you close it.

If you resolve a thread as “won’t fix” and the code around it later changes, the thread turns outdated and the finding appears once more at its new line. Each such change can add one new thread, never more. To stop a finding from coming back, change what gets reviewed instead of resolving the thread. .commitbriefignore removes the file from the review. A COMMITBRIEF.md rule only asks the model not to flag it, which usually but not always holds. An inline commitbrief-ignore marker also works; see below.

Inline suppression

Requires v1.21.0 or later. remote pr honors commitbrief-ignore markers in the lines the PR adds. A marker silences the finding on its line, or on the line below it, exactly as in a local review. Markers are read from the whole PR diff, so under --since-last-review a marker added in an earlier commit still counts even when it is outside the new commits.

Because the finding is removed before the sync, it posts no comment and any thread CommitBrief had opened for it is resolved as gone. With --no-post the same suppression applies to the local preview: the finding is absent from the output, --json carries meta.suppressed, and --fail-on works on the remaining findings. In both modes an M suppressed line goes to stderr unless --quiet is set.

The baseline is still not applied by remote pr. It is a private file on your machine, not part of the PR.

Permissions and tokens without resolve rights

Reading threads needs pull-requests: read; posting, editing, replying, and resolving need pull-requests: write; the compare request behind --since-last-review needs contents: read. The GitHub Action grants these to the workflow token.

Whether a token may resolve a thread is checked per thread at runtime. When it may not, CommitBrief degrades instead of failing:

  • A finding that disappeared gets one reply, No longer present as of <sha>, and the thread stays open.
  • If that finding later returns while the thread is still open, one reply Present again as of <sha> follows. Each transition is replied once, not on every run.
  • An outdated thread is not moved to the new line: a new comment could never be paired with closing the old one, so the old thread stays the single place where the finding is visible.

If the review threads cannot be read at all, the run warns and posts like before, without syncing.

With path filters

With --file, --dir, --exclude-file, or --exclude-dir, only threads on the files that were actually reviewed take part. Threads on other files are left alone, since nobody looked at them this run. If the filters match no file, the sync is skipped (the verdict is still submitted).

Incremental review (--since-last-review)

Requires v1.20.0 or later. On a long PR, a one-line follow-up push does not need a full re-review:

commitbrief remote pr 42 --since-last-review

CommitBrief finds its newest review of the PR that carries a reviewed marker and reviews only the commits added since then, through GitHub’s compare API. Local git is never written. Comments are still anchored against the full PR diff, so they land on the lines GitHub shows.

  • Nothing new. If the head has not moved, it prints no new commits since last review and submits nothing.
  • Fallback to a full review, with a one-line notice, when: earlier reviews cannot be read or none carries a marker; the head was force-pushed or rebased (the last reviewed commit is no longer an ancestor); a new commit is a merge commit; the compare request fails or lists too many commits to inspect; or the range diff cannot be fetched.
  • Resolving is narrower. An incremental run only resolves a disappeared finding’s thread when that thread is outdated and its file is in the new range, since an untouched file is absent because it was not looked at, not because it was fixed.
  • No approval while threads are open. While any CommitBrief thread (held ones included) is still open, or the threads cannot be read, an incremental run submits comment instead of approve. Run a full review to clear the verdict.
  • Removed lines go to the review body. A finding on a line that only exists on the old side of the range is not posted inline; it is listed in the review body.
  • Only runs without a path filter advance the marker. A run narrowed with a path filter, or one whose scope came out empty, writes no reviewed marker, so the next incremental run continues from the last marked review. The flag can be combined with the filters.

The verdict

A request-changes verdict is opt-in: it is only ever submitted when you pass --request-changes-on <sev>. Inline comments are posted regardless of the verdict. Severity order (high → low): critical, high, medium, low, info.

Without --request-changes-on (default):

SituationVerdict
No findingsapprove
Only info findingscomments posted, then approve
Any non-info findingscomments posted, then comment

With --request-changes-on = flag (opt-in):

SituationVerdict
No findingsapprove
Only info findingscomments posted, then approve
Any finding at or above flagcomments posted, then request-changes
Findings exist but none reach flagcomments posted, then comment

Never approve (--max-verdict)

Requires v1.22.0 or later. An approve is submitted under the identity gh is logged in with, and on a repository that requires a review it can satisfy that rule without a person having read the PR. --max-verdict comment switches the automatic approval off:

commitbrief remote pr 42 --max-verdict=comment

The cap is applied last, after the table above and after the incremental-run downgrade: an approve becomes comment, nothing else changes. It never touches request-changes, which stays governed by --request-changes-on alone.

--request-changes-on--max-verdictNo findingsOnly infoFindings, none at/above the thresholdAny at/above the threshold
unsetapprove (default)approveapprovecommentcomment
unsetcommentcommentcommentcommentcomment
setapprove (default)approveapprovecommentrequest-changes
setcommentcommentcommentcommentrequest-changes

Inline comments, the comment cap, the thread sync and the reviewed marker do not depend on the cap: a capped review still records that it reviewed the PR, it only declines to approve. The review body is the usual comment body. An approve that an earlier run already submitted stays on GitHub; a later comment review does not dismiss it.

Comment volume

When flag is critical or high: all critical/high findings are posted, and everything below is capped at 10 comments. When flag is medium or low: every finding at or above flag is posted, with no cap.

Machine-readable report (--json)

Requires v1.22.0 or later. In posting mode, --json writes one JSON document when the run ends, to stdout or, with --output <file>, to a file. It is for scripts and bots that drive remote pr unattended and would otherwise have to parse the localized stderr.

commitbrief remote pr 42 --json                      # document on stdout
commitbrief remote pr 42 --json --output report.json # document in a file

--json does not stop the run from posting. remote pr 42 --json posts the inline comments, submits the verdict, and also writes the document. For a local preview that writes nothing to GitHub, add --no-post. With --no-post --json the output is the plain review document, without the remote block below.

With --output, the file is opened before anything is posted, so an unwritable path fails the run up front and nothing reaches GitHub. Once the file has been opened, a run that writes no document leaves it empty (or absent, if it did not exist), the same signal as an empty stdout, so a stale report is never mistaken for this run’s result.

--markdown, --copy, --compact, and --output without --json are still rejected in posting mode. stderr is the same with or without --json: the progress tree, the Synced: line and the footer are unchanged.

The document is the JSON v1 review document (schema stays 1) with one extra top-level field, remote, that is present only in this mode:

FieldMeaning
findings[]Every finding the verdict was computed from, after inline suppression. The comment cap does not shrink it, and findings without an inline anchor are included.
meta.usage, meta.cost_usd, meta.latency_msSummed over every provider call of the run: both attempts when the PR head moved and the review was retried, plus any repair retry of an unparsable answer. The stderr footer shows the same totals.
remote.statussubmitted, no_new_commits, degraded, too_volatile or failed.
remote.pr, remote.head_oidThe repository (owner/name), the PR number, and the full commit the review was produced against.
remote.verdict, remote.verdict_uncapped, remote.max_verdictThe verdict that was submitted (or attempted), the verdict before --max-verdict was applied, and the effective cap.
remote.reviewmode (full, incremental or none), full_reason when it was a full review (for example not_requested, no_marker, not_ahead, merge_commit), previous_oid, attempts (provider-call attempts, 0 to 2) and marker_written.
remote.syncThe counters of the Synced: line (posted, updated, unchanged, resolved, replied, held) plus post_failed and unanchored, and a mode: synced, post_only (the thread list could not be read) or skipped (a path filter left nothing to review). Absent when nothing was posted.
remote.warnings[]Stable code values such as secrets_detected (a count only, never the matched text), race_retry, comment_post_failed, thread_read_failed and cost_unknown; always present, empty when there is nothing to report. They do not depend on --quiet.
"remote": {
  "status": "submitted",
  "pr": { "repo": "owner/name", "number": 42 },
  "head_oid": "3f2c9a1e…",
  "verdict": "comment",
  "verdict_uncapped": "approve",
  "max_verdict": "comment",
  "review": { "mode": "incremental", "previous_oid": "9a1b04c…", "attempts": 1, "marker_written": true },
  "sync": { "mode": "synced", "posted": 2, "updated": 1, "unchanged": 4, "resolved": 1,
            "replied": 0, "held": 0, "post_failed": 0, "unanchored": 0 },
  "warnings": [ { "code": "secrets_detected", "count": 1 } ]
}

When a document is written

The exit code stays the authority: 0 when the review was submitted (or there was nothing new to review), 1 on an error. remote.status explains it. Once any provider call has returned, every way the run ends writes the document, so the spend is never invisible:

statusWhenExit
submittedThe review was submitted.0
no_new_commits--since-last-review found the head already reviewed.0
degradedThe provider answer could not be parsed into findings; nothing was posted. content holds the raw text and meta.degrade_reason says why.1
too_volatileThe PR head moved twice; nothing was posted.1
failedAny other error after a provider call returned (for example the submit). Comments may already be posted; the next run converges.1

An error before any provider call returned (a bad flag, gh missing, a self-PR, the first fetch, or the first provider call failing) writes no document: stdout is empty and the exit code is 1. A provider call that errors or times out returns no usage, so it is not counted; treat a failed run or a missing document as “cost unknown”, not zero. Treat an unknown status as “not submitted” and trust the exit code.

Behavior notes

These describe the default posting mode; --no-post inverts most of them (it renders locally, so CLI providers, --fail-on, --json, and self-PRs all become available).

  • API providers only. claude-cli / gemini-cli / codex-cli are refused at preflight — they emit prose, not the structured findings this command needs. (Available under --no-post.) See CLI providers.
  • --fail-on is ignored (with a warning). The GitHub verdict replaces the exit-code gate; the process exits 0 on a successful review submission and non-zero only on a real error.
  • --markdown / --copy / --compact are rejected, and so is --output without --json — the output channel is GitHub, not a local renderer. --json is accepted: it writes the report and still posts.
  • No cost preflight. Posting mode never asks to confirm an estimated cost, and --no-cost-check has no effect there. For unattended runs, read the cost from the report.
  • Repository code is never executed. remote pr never runs review.sandbox_command, whatever --sandbox-rerun or review.sandbox_rerun say, in either mode.
  • Path filters apply in both modes. --file / --dir and --exclude-file / --exclude-dir narrow the reviewed file set consistently, whether the run posts to GitHub or renders locally under --no-post.
  • Commit filters are rejected. remote pr gets its diff from gh pr diff, not from local git, so there is no history to walk.
  • Self-PR is blocked. GitHub does not allow reviewing your own PR; CommitBrief rejects it before fetching the diff.
  • Pre-send guards run in warn-only mode. The secret scanner warns but does not abort — it’s the PR author’s code, not your local config.
  • Race-safe. If the PR head moves while the review runs, CommitBrief retries once; a second move aborts (PR too volatile) without submitting a review. Both attempts are counted in the footer’s tokens and cost.
  • Per-comment failures are tolerated. A comment GitHub rejects (e.g. a line not in the diff → 422) is logged and skipped; the verdict still submits, and a Posted X/Y comments, Z failed summary is printed.
  • Posted text is English. Comment and verdict bodies are fixed English (PRs are read by mixed-locale teams); only local stderr progress and error lines are localized.

Requirements

  • The gh CLI on PATH, authenticated (gh auth login).
  • An API provider configured (commitbrief setup).

See also