// 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.

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.

Added in v1.1.0.

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 --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. Changed in v1.5.0 (was `critical` by default). Ignored under `--no-post`.
`--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. Added in v1.3.0.

Inherited globals that apply: --provider / --model / --lang, --no-cache, --allow-secrets, --verbose / --quiet. 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 (v1.3.0) 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	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`	drives the verdict	ignored (noted)
Self-PR	blocked by GitHub	allowed (nothing is submitted)
Cache	not used	used (diff-hash, like a local review)

--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.

The verdict

A request-changes verdict is opt-in (since v1.5.0): 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`

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.

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.
--json / --markdown / --output / --copy / --compact are rejected — the output channel is GitHub, not a local renderer.
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.
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).