Review pull requests automatically

Reviewing a pull request instead of a local diff means posting the findings somewhere a reviewer will actually see them — as comments on the PR itself. There are two ways to get there: the official GitHub Action in comment mode, or running commitbrief remote pr yourself from any CI system that has a gh-authenticated token.

The fast path: the GitHub Action

# .github/workflows/commitbrief.yml
name: CommitBrief
on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: CommitBrief/commitbrief-action@v1
        with:
          provider: anthropic
          api-key: ${{ secrets.ANTHROPIC_API_KEY }}

comment is the Action’s default mode — no mode: input needed for this. Under the hood it runs commitbrief remote pr <number> against the pull request that triggered the workflow. The full inputs table, permissions per mode, and the secrets/env-var mapping for each provider are in the Action reference.

By default the workflow always finishes with exit code 0 once comments post successfully, no matter how severe the findings are — posting a comment isn’t a gate. What you can change is the GitHub review verdict itself (approve vs. request changes) with request-changes-on:

      - uses: CommitBrief/commitbrief-action@v1
        with:
          provider: anthropic
          api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          request-changes-on: high

That verdict never touches the check’s exit code — it’s still 0 either way. If you want CI itself to fail on severity, that’s the gate mode covered in CI gating, and the two can run as separate jobs in the same workflow.

Running it yourself: commitbrief remote pr

If you’re not on GitHub Actions, or want more control than the Action input surface exposes, call the command directly from any CI runner that has an authenticated gh and an API provider configured:

commitbrief remote pr 42
commitbrief remote pr owner/repo#42 --request-changes-on=high

It accepts a bare PR number (current repo), an owner/repo#N reference, or a full PR URL. This is exactly what the Action’s comment mode runs on your behalf, so everything about the verdict, comment volume, and behavior notes in the full reference applies here too.

Try it without posting anything

--no-post runs the full review and prints what would be posted — useful for wiring up a new pipeline without spamming a real PR while you get the setup right:

commitbrief remote pr 42 --no-post

See read-only mode for exactly how it differs from posting mode.

Things worth knowing before you turn this on

• API providers only. The CLI-backed providers (claude-cli, gemini-cli, codex-cli) aren’t supported here — see provider setup for which ones are.
• --fail-on is ignored (with a warning) in posting mode — posting a comment isn’t a gate, so there’s nothing for it to enforce there. It’s honored under --no-post, since that mode doesn’t post at all. Use gate or guard in a separate job to actually fail the check.
• Comment volume depends on --request-changes-on. With the flag unset, or set to critical/high, critical and high findings always post in full and everything below is capped at 10. Set it to medium or low instead and the cap disappears — every finding at or above that level posts, uncapped. See the comment volume rules for the exact table.
• A self-authored PR is blocked — you can’t have CommitBrief review your own open PR under the same identity the token authenticates as.

See also

• GitHub Action — full inputs, permissions, and CLI version floors for comment/gate/guard modes.
• commitbrief remote pr — the complete flag and behavior reference.
• CI gating — failing a check on severity instead of (or alongside) commenting.