# 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 docs · v1.x · Reviewing

Canonical URL: https://commitbrief.com/docs/1.x/remote-pr

---

`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](https://cli.github.com), 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](/docs/1.x/severity#the-official-github-action)
wraps this same command.

Added in v1.1.0.

## Usage

```sh
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](#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](#read-only-mode---no-post). 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:

```sh
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`](#read-only-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](/docs/1.x/providers#claude-cli-gemini-cli-and-codex-cli).
- **`--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.
- **Path filters apply in both modes.** `--file` / `--dir` (and the
  v1.15.0 `--exclude-file` / `--exclude-dir`) narrow the reviewed
  file set. Before v1.15.0 only the `--no-post` path honored them,
  so a narrowed run that commented on GitHub reviewed a *different*
  file set than the same command with `--no-post` — fixed in
  v1.15.0.
- **[Commit filters](/docs/1.x/review-scopes#commit-filters-v1150)
  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.
- **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](https://cli.github.com) on `PATH`, authenticated
  (`gh auth login`).
- An API provider configured (`commitbrief setup`).

## See also

- [Review scopes](/docs/1.x/review-scopes) — review a local range
  instead of a PR.
- [Severity and CI gating](/docs/1.x/severity) — what
  `--request-changes-on` ranks against, plus the GitHub Action.
- [Providers](/docs/1.x/providers#claude-cli-gemini-cli-and-codex-cli) — why
  CLI providers are refused here.