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.
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
| Flag | Default | Effect |
|---|---|---|
--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> | approve | Cap 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-post | false | Review the PR diff and render it locally — write nothing back to GitHub. See Read-only mode. |
--since-last-review | false | Review 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
| Aspect | Posting mode (default) | --no-post |
|---|---|---|
| GitHub writes | inline comments + verdict | none |
| Output | GitHub, plus the report with --json | terminal (--json / --markdown / --output / --copy / --compact) |
| Providers | API only | API or CLI (--cli) |
--fail-on | ignored (verdict replaces it) | applies (exit code) |
--request-changes-on / --max-verdict | drive the verdict | ignored (noted) |
| Self-PR | blocked by GitHub | allowed (nothing is submitted) |
| Cache | not used | used (diff-hash, like a local review) |
Inline commitbrief-ignore | applied before the sync | applied 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-ignoremarker 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-reviewreads 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 reviewand 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
commentinstead ofapprove. 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
reviewedmarker, 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):
| Situation | Verdict |
|---|---|
| No findings | approve |
Only info findings | comments posted, then approve |
| Any non-info findings | comments posted, then comment |
With --request-changes-on = flag (opt-in):
| Situation | Verdict |
|---|---|
| No findings | approve |
Only info findings | comments posted, then approve |
Any finding at or above flag | comments posted, then request-changes |
Findings exist but none reach flag | comments 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-verdict | No findings | Only info | Findings, none at/above the threshold | Any at/above the threshold |
|---|---|---|---|---|---|
| unset | approve (default) | approve | approve | comment | comment |
| unset | comment | comment | comment | comment | comment |
| set | approve (default) | approve | approve | comment | request-changes |
| set | comment | comment | comment | comment | request-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:
| Field | Meaning |
|---|---|
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_ms | Summed 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.status | submitted, no_new_commits, degraded, too_volatile or failed. |
remote.pr, remote.head_oid | The repository (owner/name), the PR number, and the full commit the review was produced against. |
remote.verdict, remote.verdict_uncapped, remote.max_verdict | The verdict that was submitted (or attempted), the verdict before --max-verdict was applied, and the effective cap. |
remote.review | mode (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.sync | The 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:
status | When | Exit |
|---|---|---|
submitted | The review was submitted. | 0 |
no_new_commits | --since-last-review found the head already reviewed. | 0 |
degraded | The provider answer could not be parsed into findings; nothing was posted. content holds the raw text and meta.degrade_reason says why. | 1 |
too_volatile | The PR head moved twice; nothing was posted. | 1 |
failed | Any 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-cliare refused at preflight — they emit prose, not the structured findings this command needs. (Available under--no-post.) See CLI providers. --fail-onis ignored (with a warning). The GitHub verdict replaces the exit-code gate; the process exits0on a successful review submission and non-zero only on a real error.--markdown/--copy/--compactare rejected, and so is--outputwithout--json— the output channel is GitHub, not a local renderer.--jsonis accepted: it writes the report and still posts.- No cost preflight. Posting mode never asks to confirm an estimated
cost, and
--no-cost-checkhas no effect there. For unattended runs, read the cost from the report. - Repository code is never executed.
remote prnever runsreview.sandbox_command, whatever--sandbox-rerunorreview.sandbox_rerunsay, in either mode. - Path filters apply in both modes.
--file/--dirand--exclude-file/--exclude-dirnarrow the reviewed file set consistently, whether the run posts to GitHub or renders locally under--no-post. - Commit filters
are rejected.
remote prgets its diff fromgh 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 failedsummary 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
ghCLI onPATH, authenticated (gh auth login). - An API provider configured (
commitbrief setup).
See also
- Review pull requests automatically — a
guided walkthrough of this command and the GitHub Action’s
commentmode. - Review scopes — review a local range instead of a PR.
- Output formats — the JSON document the report extends.
- Severity and CI gating — what
--request-changes-onranks against, plus the GitHub Action. - Providers — why CLI providers are refused here.