GitHub App guide

The GitHub App runs review work in response to pull-request webhooks and PR comments. Repository access always comes from the installation attached to the target repository. The Worker does not fall back to another installation when the App belongs to more than one account.

Install and subscribe

Configure the GitHub App with this webhook URL:

https://codebeaver.workers.dev

The Worker accepts POST webhooks at the root path. Every delivery must include a valid x-hub-signature-256 HMAC. Bodies larger than 1 MB return HTTP 413.

Subscribe to these events:

Event	Actions used
Pull request	opened, synchronize, reopened, ready for review, converted to draft, edited, labeled, unlabeled, closed
Issue comment	created
Pull request review	submitted, dismissed
Pull request review comment	created, edited, deleted
Pull request review thread	resolved, unresolved
Merge queue entry	added
Installation	created, deleted

The pull_request labeled action triggers label handling. There is no separate GitHub label event for this flow.

Install the App only on repositories it should read and review. Repository-writing commands also require the installation to have the corresponding GitHub permission.

The installation ID on a webhook is carried into review and command jobs. Legacy jobs without one resolve the repository installation before making a GitHub call. Token creation rejects a missing or invalid ID, and no code path falls back to the first installation on the App.

Automatic review gates

An opened, synchronized, reopened, ready-for-review, or eligible edited PR reaches the review pipeline only after the configured gates pass.

The checks include:

• auto_review.enabled or an opt-in description_keyword;
• draft handling;
• ignored usernames and title terms;
• target branch patterns;
• positive and negative label rules;
• test-only review mode;
• per-repository pause and per-PR ignore state;
• in-flight review and reviewed-SHA deduplication;
• global or repository rate limits.

Dependabot PRs are skipped before repository review gates. Other bot users can be listed explicitly in auto_review.ignore_usernames.

Skipped PRs get a bounded skip notice where the handler has enough context to explain the reason. Duplicate GitHub delivery IDs are ignored for five minutes.

Pre-reviewed commits

Hosted CLI reviews (codebeaver review) record the reviewed commit SHA and ignore-filtered diff for 30 days when the user has push access and validation completed. Truncated reviews and profile/focus overrides cannot satisfy the remote check. Older records without full-coverage evidence require a fresh review. With auto_review.previously_reviewed: skip, an automatic review of a head whose remote diff matches that local review finalizes the AI Code Review check from the recorded verdict instead of running the models again, posts a short notice, and advances the reviewed-SHA pointer. approve maps to a green check, request_changes to red. Manual /review always forces a fresh pass; the default recheck mode reruns the review normally.

The labels needs-review, ready-for-review, and please-review trigger a manual-style review when added to a non-draft PR. They are independent of auto_review.labels, which controls whether ordinary automatic reviews are eligible.

Commands and permissions

The default handle is @codebeaver. Set BOT_HANDLE to use another handle.

Command	Result	Permission checked by the bot
/review	Queue a fresh full review	none beyond repository visibility; clearing @bot ignore requires write and clearing /review cancel requires maintain
/review cancel or @bot cancel	Cancel the queued or active AI review	maintain
/ask <question> or @bot ask <question>	Answer a question using the PR diff	none
/coverage or @bot coverage	Report changed source files and likely matching tests	none
@bot changelog or /changelog	Post a generated changelog entry	none
@bot improve	Post code improvement suggestions	none
@bot simplify	Post refactoring suggestions	none
@bot fix ci	Run a fresh CI-repair-focused review	none
@bot fix merge conflict or @bot resolve conflict	Prepare conflict-resolution input for verified autofix	write (stages the verified-autofix chain)
@bot autofix	Post AI-generated inline fix suggestions	write
@bot autofix --apply [path:line,...] or @bot autofix apply	Add auto-fix and queue a verified follow-up PR	write, plus direct-apply checks
@bot implement [--apply] or @bot implement apply	Alias for autofix	write
@bot fix ci --apply	Queue a verified CI-repair branch	write on the apply path
@bot describe or /describe	Update the PR description	write
`@bot run security	performance	types
@bot config	Post the config source plus a selected summary of the effective merged config	write
@bot config generate	Post a starter YAML block; it does not commit a file	write
@bot generate docstrings	Open a follow-up PR with generated docstrings	write
@bot generate unit tests	Open a follow-up PR with generated tests	write
@bot resolve	Resolve the bot's review threads	write
@bot ignore	Stop automatic reviews for this PR until /review	write
@bot pause / @bot resume	Pause or resume automatic reviews for the repository	maintain
@bot help or /help	Post the current command table	none
@bot <question> or `@bot explain	what	how

@bot config reads the same org and repository layers as an automatic review. Its reply is a summary, not a dump of every effective field.

A manual /review may run on a draft. Requests for a queued or active head reuse the existing run. A request for a newer head replaces an older queued message or waits for an active review, and scheduled cleanup requeues it if the handoff is missed. /review cancel and @bot cancel are maintainer-only commands that stop queued and retrying jobs before consumption and request cancellation for active runs. Closing the PR cancels a queued manual run before consumption. On a closed PR, one manual review is allowed after close cleanup; repeated closed-PR reviews return a conflict response.

Long-running commands use one editable operation comment. It says Waiting to start while queued, then reports its ordered stages, revised remaining time, and UTC ETA. Terminal headings use the shared states queued, running, retrying, completed, skipped, cancelled, and failed. Permission, retryable, partial, and blocking outcomes use GitHub alert blocks with the next action.

Review output

A normal run creates or updates four GitHub surfaces:

1. an AI Code Review check run with phase status and a final conclusion;
2. a status comment while the review is in progress, with current stage, remaining time, UTC ETA, and elapsed time;
3. a walkthrough comment with the verdict and finding count above the fold, followed by collapsed supporting sections for summary, checks, linked issues, affected consumers, an evidence-backed architecture-impact diagram when the local graph has enough relationships, usage, and review metadata;
4. a GitHub review containing inline findings and an approve, comment, or request-changes state.

publication.output_mode can limit publication to the walkthrough (summary), inline review plus a short batch comment (inline), or both surfaces. The analysis, validation, scanner, storage, retry, and check-run paths still run in every mode. Review-generated questions appear in the walkthrough only when enabled; they are advisory and cannot block a pull request.

The verdict and check conclusion are related but separate:

Findings	GitHub review	Default check conclusion
none	approve	success
suggestions only	comment	neutral
warning	request changes	neutral
critical	request changes	failure
blocked secret or failed custom pre-merge check	request changes	failure

Change check_run.blocking_severities to make warnings or suggestions fail the check. Critical secrets still fail when pre_merge_checks.block_secrets is on.

When every changed file matches the repository's ignore paths, including a generated-only PR, the Worker posts a skip notice and completes the AI Code Review check successfully. It does not create a second neutral check run.

Provider outages (CB-1731)

When every configured review model fails for provider infra reasons (billing/credits 402, invalid credentials 401, model access 403 — the **AI review blocked** path), the Worker still posts a clear PR comment, but the check run concludes neutral — not failure. Transient timeouts, empty output, malformed completions, and exhausted output caps also finalize as neutral and queue a retry. The Worker never publishes an unvalidated provider response as a review result. Comment /review after providers are healthy.

This is intentional permanent behavior (not a temporary workaround). Real code findings still map to success / neutral / failure via deriveCheckConclusion as above.

On later commits, the Worker compares findings with the previous head, dismisses stale bot change requests, keeps already-reported same-head locations quiet, and reports resolved or still-open findings in the walkthrough.

If the head changes while a review is being posted, the analyzed SHA is never rewritten. The old check and walkthrough are marked superseded, findings and reactions are skipped, and a new review is queued for the current head. A same-head posting error remains visible as a posting failure.

Focused review recipes

@codebeaver run security
@codebeaver run performance
@codebeaver run types
@codebeaver run scope

Recipes append a bounded instruction to the ordinary review context. scope compares the changed behavior with the available PR description and linked issues, but never invents requirements when they are absent. Recipes still run deterministic checks and the normal finding filters. Unknown recipe names produce a comment listing the accepted names.

Verified autofix

Verified autofix separates code generation from repository verification:

PR comment or CLI
  -> add auto-fix label
  -> reusable workflow calls /api/cli/autofix
  -> Worker creates codebeaver/autofix/* branch
  -> workflow checks out that branch
  -> repository commands run with a timeout
  -> passing commands open a PR against the original PR branch

The source PR must come from a branch in the same repository. Fork PRs are reported and skipped. A failing verification run keeps the generated branch for inspection and does not open a follow-up PR.

Bring-your-own-key review

actions/byok-review is a JavaScript GitHub Action. It fetches a PR diff through the GitHub API, sends that diff to an OpenAI-compatible provider you choose, and writes SARIF 2.1.0. It never checks out or executes PR code, posts no PR comments, and does not use pull_request_target. GitHub requests time out after 30 seconds; provider requests time out after two minutes. Its model findings are explicitly marked unvalidated; they are separate from the hosted two-pass reviewer result.

Use it only on same-repository PRs. GitHub withholds repository secrets from fork PRs, and this workflow deliberately does not work around that boundary.

name: BYOK PR review

on:
  pull_request:
    types: [opened, reopened, synchronize, ready_for_review]

permissions:
  contents: read
  pull-requests: read
  security-events: write

jobs:
  review:
    if: github.event.pull_request.draft == false && github.event.pull_request.head.repo.fork == false
    runs-on: ubuntu-latest
    steps:
      - id: review
        uses: codebeaver/codebeaver/actions/byok-review@main
        with:
          provider-api-key: ${{ secrets.REVIEW_PROVIDER_API_KEY }}
          provider-base-url: https://openrouter.ai/api/v1
          model: openai/gpt-4o-mini
          github-token: ${{ github.token }}
          pull-request: ${{ github.event.pull_request.number }}
          output: codebeaver-byok.sarif
          fail-on: none

      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: ${{ steps.review.outputs.sarif-file }}

Set fail-on to error, warning, or any only if you want the action to fail after writing SARIF. Keep the upload step under if: always() when you need GitHub code scanning to retain a report from a blocking run.

Add this workflow to a caller repository:

name: CodeBeaver Auto-Fix

on:
  pull_request_target:
    types: [labeled]

jobs:
  auto-fix:
    if: github.event.label.name == 'auto-fix'
    uses: codebeaver/codebeaver/.github/workflows/auto-fix.yml@main
    secrets: inherit

Then configure the commands in .codebeaver.yaml:

autofix:
  verification:
    enabled: true
    timeout_minutes: 20
    commands:
      - pnpm install --frozen-lockfile
      - pnpm lint
      - pnpm typecheck
      - pnpm test

Selected apply syntax limits generation to stored finding locations:

@codebeaver autofix --apply src/auth.ts:42,src/session.ts:18

The Worker stores selected locations for ten minutes. Exact replacement patches use a 21-day cache whose identity includes repository, source blob SHA, path, line, and suggestion hash. Raw source is not part of the cache name.

Merge conflicts

@bot fix merge conflict uses the compare API to find files changed on both sides since the merge base. It supports ordinary content conflicts for up to the configured bounds. Deleted files, renames, submodules, fork PRs, and files that cannot be merged are reported for manual work.

CI repair

@bot fix ci includes failed check annotations and bounded check output in a fresh review. The non-apply form only posts findings. @bot fix ci --apply stores a focused repair prompt, adds auto-fix, and runs the same verified branch flow.

Dependabot repair

POST /api/cli/dependabot-repair is for a caller repository's workflow_run controller after its read-only CI fails. It accepts only an open Dependabot pull request that targets main from a branch in the same repository. One attempt is recorded per pull request for 30 days.

The Worker reads bounded CI failure details, asks the configured autofix model for a repair, and can update the Dependabot branch only when every proposed change is already in the dependency pull request's diff. It refuses workflows, scripts, tests, deployment configuration, migrations, lockfile settings, and access-control code. The controller must never check out or execute pull request code. The pushed repair starts the caller repository's ordinary, read-only CI again.

Feedback and learning

The reviewer records human signals from:

• dismissed bot reviews;
• resolved and reopened review threads;
• replies to bot inline comments, including edits and deletions;
• reactions collected when a PR merges;
• findings absent on a later commit;
• fixes applied by autofix.

Dismissed findings are suppressed for that PR by normalized issue and file, regardless of line movement. Built-in deterministic findings are never suppressed by dismissal.

Learned false-positive and practice rules expire after 90 days without fresh feedback. Scheduled cleanup removes invalid and stale rules, merges duplicates, and retains at most 50 per list and repository. New rules can remain pending until an operator approves or rejects them in the dashboard or CLI.

Merge queue

When a merge_queue_entry is added, the Worker fetches the queued PR diff, applies ignore and SAST exclusions, and checks for critical deterministic or stored review findings. A failure posts a PR comment. A pass comment is posted only when stored findings exist and secret blocking is enabled. This handler does not create a merge-blocking check or commit status.

Close, draft, and retry behavior

Closing a PR sets a cancellation marker, cleans abandoned status comments and check runs, and dismisses stale bot change requests when needed. Merge handling also collects reactions, updates learning data, and refreshes vectors for changed, deleted, or renamed files.

Converting a PR to draft cancels in-flight work and dismisses stale bot reviews. Marking it ready clears the in-flight gate and starts a fresh review.

The review queues run at most twelve jobs at once: ten normal consumers and two reserved consumers for PRs in codebeaver/codebeaver. Reviewer PRs use that reserved lane so they are not held behind unrelated repository work.

If a manual /review arrives while another review is active for the same head, the Worker ignores it. A request for a newer head is retained with that head SHA and released after the active run. Scheduled cleanup also requeues any deferred request that missed the handoff.

The scheduled Worker runs every five minutes. It cleans expired review state, compacts learning rules, recovers KV-tracked abandoned checks, and retries queued work. A recovery retains its in-flight marker if GitHub cannot complete the old check run, so a new check is not started beside a stuck one. The marker-missing fallback scans five repositories every 30 minutes to leave GitHub App capacity for active reviews. Provider denials caused by billing, credentials, or model access are terminal for that run and are not treated as transient orphan retries.