reviewer

Pull request review by Claude Code, run in GitHub Actions when someone asks for it.

What it does

• Reviews a pull request only on request: a team review request or a comment command. Pushes never start a review.
• Runs Claude Code headless with a multi-agent review skill. The code-reviewer agent always runs; language and security specialists join when the changed files call for them.
• Posts one GitHub review per run. Each finding is graded blocker, follow-up or nit, with evidence and a suggested fix.
• Derives the verdict from fixed rules, not from the model. Any blocker requests changes.
• Approves only low-risk PRs: no blockers, green CI, no high-risk paths, not from a fork or a bot, and approvals switched on for the repo.
• Escalates to the code owners in CODEOWNERS when a change needs a human: a blocker on an owned path, high risk, or a design question.
• Re-reviews only the new commits when asked again, resolves the threads of fixed findings, and takes feedback on its findings.
• Optionally runs deterministic modules beside the review, such as a repository's Rerail rules. A second, smaller rules pass turns their new findings into labelled recommendations. A new breach of an enforced rule is a blocker. The first review never sees module output. On a schedule, the same modules scan the whole branch.

The bot posts as a GitHub App you create. This repository's examples use the app neralabs-reviewer (handle @neralabs-reviewer) and the team @neralabs/reviewer.

How it works

flowchart LR
  E[PR event in a target repo] --> C[caller workflow]
  C --> G{gate: trigger, permission, state}
  G -->|ignore| X[exit]
  G -->|help / stop| S[respond job: app token]
  G -->|review| R[review job: Claude Code + review skill, read-only]
  R --> J[findings.json]
  J --> P[post job: app token]
  P --> GH[review, inline comments, resolved threads, reviewer requests]

The model reads untrusted PR content, so it never holds a credential that can write. The review job has no GitHub token and no shell; it produces findings.json and nothing else. A separate post job validates and sanitises that output, re-reads the PR from GitHub, applies the verdict rules and posts. Details: docs/architecture.md and docs/security-model.md.

Quickstart

These steps set the reviewer up for your organization. Replace <org> with your organization and <app> with your app's name.

1. Create a GitHub App in your organization (Settings → Developer settings → GitHub Apps). Permissions:

   • Repository: Pull requests read and write, Contents read, Metadata read. If the bot's approvals should count toward required reviews, give it Contents read and write instead: GitHub counts an approval only from an account that can write to the repository. The workflow's tokens ask for read access to contents either way.
   • Organization: Members read. GitHub ignores an app's changes to team review requests without it.
   • No webhook: clear "Active" under Webhook.

   Generate a private key. Note the app's client ID.

2. Install the app on each repository it should review. It needs access to those repositories only.

3. Create a team for review requests, for example <org>/reviewer. Remove every member, including yourself (GitHub adds the creator), and turn notifications off. Give the team read access to each target repository, so it can be requested as a reviewer.

4. Store the credentials as organization or repository settings visible to the target repositories:

   • variable REVIEWER_APP_CLIENT_ID: the app's client ID;
   • secret REVIEWER_APP_PRIVATE_KEY: the app's private key;
   • the model credential: secret REVIEWER_ANTHROPIC_API_KEY (a Claude API key), or secret REVIEWER_BEDROCK_API_KEY (an Amazon Bedrock API key). Scope the key to invoking the model you configure and nothing else. infra/bedrock.yml is a CloudFormation example for Bedrock.

5. Add the caller workflow. Copy templates/caller.yml to .github/workflows/reviewer.yml in the target repository. Set provider and model, pin uses: and reviewer_ref to a release tag (docs/versioning.md), and set team_slug, handle and bot_login for your app and team (docs/configuration.md). Keep the explicit list; don't use .

Start with allow_approve: false. The bot then comments and requests changes but never approves. Turn approvals on once its reviews are reliable for the repository. When the app has Contents read and write, bot approvals count toward required reviews, so treat the caller, REVIEW.md and CODEOWNERS as security-relevant files. With Contents read, the bot still posts approvals, but a person's approval is still required.

Commands

Only users with write access to the repository can trigger the bot. It ignores bots, quoted lines and fenced code.

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗