Configuration reference

Place .codebeaver.yaml at the repository root. For pull request reviews, the Worker reads the repository file from the target branch's base commit. A PR cannot change the policy that reviews itself; configuration changes take effect after merge. A missing or invalid file falls back to defaults and does not stop the review.

Inheritance

Configuration has three layers:

1. built-in defaults;
2. <owner>/.github/.codebeaver.yaml;
3. <owner>/<repo>/.codebeaver.yaml.

Repository values override org values for scalar settings. These lists accumulate across layers: ignore_paths, path_rules, ast_rules, auto_review label and filter lists, SAST exclusions, top-level labels, test-generation path instructions, and severity caps. These lists replace the earlier layer: autofix verification commands, external-context files, custom pre-merge checks, suggested-reviewer rules, and check-run blocking severities.

After merging, disabled_rule_ids removes matching path_rules and ast_rules from the final config, including rules declared in the repository layer itself.

The Worker logs the source as default, org, repo, or merged. Comment @codebeaver config on a PR to see the effective source and selected values.

Unknown top-level fields produce config_unknown_key warnings. Unknown nested fields are ignored.

Profiles, output, and questions

@bot run <profile> and codebeaver review --profile <profile> use the same built-in profiles: security, performance, types, scope, and mentor. --focus remains an alias for older CLI scripts. A repository can add or override named profiles under review_profiles; profile policy is still read from the pull request base SHA.

publication:
  output_mode: summary # summary | inline | both

questions:
  enabled: true
  max_questions: 3

review_profiles:
  api-contracts:
    instruction: Check compatibility of public HTTP and TypeScript contracts.
    tone: picky
    include_pr_metadata: true
    output_mode: summary
    allow_questions: true
    languages: [typescript, go]

summary posts the terminal walkthrough and check without a GitHub review. inline posts validated inline comments plus a short terminal batch comment. both retains the default output. These settings do not skip scanners, proof checks, validation, check finalization, persistence, or recovery. Questions are shown separately, never become findings, and do not affect verdicts, autofix, or merge status. The reviewer adds language-specific prompts for detected TypeScript, JavaScript, Python, Go, Rust, Java, Kotlin, and C# files without scheduling another model call.

Defaults

This YAML shows the effective built-in behavior. Empty arrays are valid.

tone: chill

telemetry:
  enabled: true

auto_review:
  enabled: true
  drafts: false
  ignore_usernames: []
  description_keyword: ""
  ignore_title_keywords: []
  base_branches: []
  labels: []
  auto_pause_after_reviewed_commits: 0
  skip_test_only_prs: false
  test_review_mode: lightweight
  # Skip when a push-authorized, validated CLI review covered this exact commit
  # and remote diff. `recheck` (default) reruns.
  previously_reviewed: recheck
  auto_describe: false

autofix:
  verification:
    enabled: true
    commands: []
    timeout_minutes: 15

slop_detection:
  enabled: true
  label: slop

delta_review:
  enabled: false
  max_files: 300

review:
  depth: standard

noise:
	quiet_mode: false
	min_severity: suggestion
	max_findings: 5

shadow_recall:
  enabled: true
  max_diff_chars: 75000
  sampling: 0.1

publication:
  output_mode: both

questions:
  enabled: false
  max_questions: 3

review_profiles: {}

external_context:
  files: []
  max_chars: 12000

stack_awareness:
  enabled: true

summarize:
  enabled: false

pre_merge_checks:
  require_tests: false
  require_description: false
  min_description_length: 20
  block_secrets: true
  require_docstrings: false
  min_docstring_coverage: 50
  block_on_docstrings: false
  custom_checks: []

pr_history:
  enabled: true
  max_count: 5

walkthrough:
  collapsed: true
  show_changed_files: true
  show_effort: true
  show_architecture_diagram: true
  show_pre_merge_checks: true
  show_related_prs: true
  show_review_info: true
  show_ai_agent_prompt: true
  show_linked_issues: true

suggested_reviewers:
  enabled: false
  auto_assign: false
  rules: []

assess_linked_issues: true
labels: []
test_generation:
  path_instructions: []
auto_describe: false

sast:
  exclude_paths: []

ast_rules: []
deterministic_pre_checks:
  enabled: true

check_run:
  blocking_severities: [critical]

severity_caps:
  - paths: ["**/*.test.ts", "**/*.test.tsx", "eval/**"]
    max_severity: suggestion

ignore_paths:
  - pnpm-lock.yaml
  - package-lock.json
  - yarn.lock
  - routeTree.ts
  - routeTree.gen.ts
  - /generated/
  - /dist/
  - /build/
  - /.next/

path_rules: []
disabled_rule_ids: []
system_prompt: null
supplementary_prompt: null

sast.exclude_paths above is the custom list. The Worker also excludes common tests, fixtures, examples, and GitHub workflows from SAST by default. See SAST exclusions.

Automatic review

auto_review:
  enabled: true
  drafts: false
  ignore_usernames: [dependabot]
  description_keyword: "!review"
  ignore_title_keywords: ["[skip review]", "release notes"]
  base_branches: [main, "release/.*"]
  labels: [backend, "!wip"]
  auto_pause_after_reviewed_commits: 20
  test_review_mode: lightweight
  auto_describe: true

Field	Meaning
enabled	Main automatic-review switch. Manual /review still works.
drafts	Allow automatic review of drafts. Manual review always may run.
ignore_usernames	Exact GitHub logins to skip.
description_keyword	Exact opt-in text when automatic review is disabled. On edited events, a configured keyword gates the event even when automatic review is enabled. Other eligible events are not gated when enabled is true.
ignore_title_keywords	Case-insensitive substrings that skip a PR.
base_branches	Regular expressions matched against the full base branch name. Invalid expressions fall back to exact matching. Empty means any base branch.
labels	Label gates. Any positive label means at least one must match. A !label entry excludes matching PRs. Matching is case-insensitive.
auto_pause_after_reviewed_commits	Pause before the threshold-triggering automatic review starts. For example, 20 reviews the first 19 eligible events, then pauses on the 20th. 0 disables it. Resume resets the counter.
test_review_mode	skip, lightweight, or full for PRs containing only test paths. Default lightweight: scanner + a focused test review instead of skipping.
skip_test_only_prs	Legacy boolean. Use test_review_mode; the explicit mode wins.
previously_reviewed	recheck (default) always runs the remote review. skip finalizes the GitHub check from a push-authorized, validated CLI review only when the full diff was analyzed without a profile or focus override, and both the head commit and ignore-filtered remote diff match. Older records without full-coverage evidence require a fresh review. A manual /review always forces a fresh run.
auto_describe	Generate a description for a newly opened PR whose body is missing or shorter than 50 characters.

Test-only mode behavior:

Mode	Deterministic checks	AI calls	Result
skip	no	no	status comment explains the skip
lightweight	yes	no	SAST, AST rules, deterministic prechecks, and the tests, description, and docstring pre-merge checks; custom model checks do not run
full	yes	yes	ordinary review pipeline

A forced manual review runs the full pipeline. A scheduled recovery of an interrupted test-only review keeps its configured skip or lightweight mode.

Autofix verification

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

The Worker returns these commands to .github/workflows/auto-fix.yml. The workflow writes a temporary shell script, checks out the generated branch, and runs the commands in order. It opens the follow-up PR only after every command passes.

Limits:

• 1 to 60 minutes;
• at most 10 commands;
• at most 500 characters per command;
• blank commands are removed.

Verification is enabled by default, but the default command list is empty. Configure at least one command before using verified apply. An empty list cannot verify a generated branch, so the reusable workflow rejects a Worker response without commands.

Finding volume and severity

noise:
  quiet_mode: true
  min_severity: warning
  max_findings: 10

severity_caps:
  - paths: ["docs/**", "**/*.test.ts"]
    max_severity: suggestion

check_run:
  blocking_severities: [critical, warning]

noise.min_severity accepts suggestion, warning, or critical. quiet_mode drops suggestions even when the minimum is lower. max_findings caps noncritical findings between 1 and 50; the default is 5. Reviews with more than 30,000 diff characters or more than five changed files automatically allow up to 10 noncritical findings unless a higher cap is configured. Critical secret matches are retained outside that cap.

Severity caps downgrade noncritical findings on matching paths. max_severity accepts suggestion or warning. Critical findings are never downgraded.

Regex scanner findings other than critical secrets go through the same diff, suppression, evidence, and validator checks as model findings. Documentation and test fixtures are excluded from regex scanning by default. Add project-specific paths under sast.exclude_paths when a directory contains generated or intentionally unsafe examples.

The PR review verdict still requests changes for warnings and critical findings. check_run.blocking_severities controls which finding severities fail the GitHub check. It accepts critical, warning, and suggestion.

Review depth

review:
  depth: standard

review.depth dials the routing and finding budget without touching any other setting. standard (default) picks the reasoning path automatically by diff size. fast always routes through the fast path — no reasoning, fast timeouts, fast-priority provider ordering — regardless of diff size, and holds the review to the configured noise.max_findings even when the diff would otherwise earn a larger budget. thorough always uses high reasoning, never the fast path, and raises the effective finding cap to at least 15.

Pre-merge checks

pre_merge_checks:
  require_tests: true
  require_description: true
  min_description_length: 80
  block_secrets: true
  operational_risk_notes: true
  require_docstrings: true
  min_docstring_coverage: 70
  block_on_docstrings: false
  custom_checks:
    - "The migration has a reversible down path."
    - "Every new public endpoint checks authorization."

require_tests looks for conventional test paths in the changed file list. It does not run the test suite. require_docstrings estimates JSDoc coverage for added functions and classes. block_on_docstrings adds an explicit merge-block message when coverage is below the threshold.

operational_risk_notes adds non-blocking walkthrough rows when the diff changes migration files, secret/config files or verified secrets, Wrangler configuration, or Terraform files. Each row names the likely blast radius and asks for a staging smoke before merge. Set it to false when a repository has a different deployment process.

Custom checks are model calls against the bounded review context. Their pass or fail rows appear in the walkthrough and failed custom checks fail the GitHub check. Their provider usage is added to the review's usage record.

Paths and prompts

Ignored paths

ignore_paths:
  - pnpm-lock.yaml
  - "**/generated/**"
  - "vendor/**"

Ignored paths are removed before prompt construction. Glob patterns use the reviewer's path matcher; plain strings match path substrings. Built-in ignore paths remain when org or repository files add more entries.

Path rules

path_rules:
  - id: worker-logging
    path: "src/**/*.ts"
    severity: warning
    enabled: true
    rules:
      - "Use src/logger.ts for Worker diagnostics."
      - "Every swallowed async failure must be logged."

disabled_rule_ids:
  - inherited-obsolete-rule

path_rules are added to the prompt only when a changed file matches path. IDs may contain letters, digits, ., _, and -, up to 80 characters. severity gives the model a maximum severity for findings based on that rule.

Repository disabled_rule_ids remove matching path and AST rules from the final merged config, regardless of which layer declared them. Setting enabled: false also removes a path rule.

Repository instructions

When supplementary_prompt is null, the Worker fetches instruction files in this order:

1. root AGENTS.md;
2. directory-scoped AGENTS.md files for changed paths, shallow to deep;
3. .github/copilot-instructions.md;
4. CONTRIBUTING.md;
5. CLAUDE.md;
6. .cursorrules.

Instruction text is capped at 48,000 characters across the selected files. Files are read at the target branch's base commit and are never executed. A PR cannot replace the instructions that govern its own review.

supplementary_prompt: |
  Treat changes to billing totals as warning or critical findings.
  Ignore formatting that Biome can fix.

An explicit supplementary prompt replaces automatic instruction-file loading. Focused commands and stack or external context may still append their own bounded sections.

system_prompt replaces the default reviewer prompt, conventions, learned-rule blocks, path rules, and tone. The Worker still appends the required JSON output contract, evidence-quote requirement, English-only output rule, and input-trust boundary. Everything else in the built-in prompt is also replaced: the size and change-type calibration tables, the three-pass review protocol, the self-verification pass, and the writing-style rules. Use it only when maintaining the full review policy yourself.

External, stack, issue, and history context

Blind-first review

blind_first_review: false

When enabled, the primary review model receives the diff and repository context without the PR title or description. This reduces intent bias during candidate generation. Linked-issue assessment continues after finding validation with ordinary PR context; the validator stays evidence-led and does not receive PR metadata. The setting is included in the review-result cache identity, so blind and ordinary reviews cannot reuse one another's result.

external_context:
  files:
    - docs/api-contract.md
    - schemas/public-api.json
  max_chars: 18000

stack_awareness:
  enabled: true

pr_history:
  enabled: true
  max_count: 5

learning:
  collect_merge_reactions: false

assess_linked_issues: true

External files must be repository-relative paths without whitespace, URLs, backslashes, or ... At most 20 paths are accepted. max_chars is clamped to 1,000 through 30,000. The Worker reads them from the target branch's base commit, so a PR cannot rewrite its own review context. Fetching stops after eight seconds and never reads another repository.

Stack awareness tells the reviewer that the head branch is one step against the base branch. It does not fetch arbitrary dependent repositories.

Linked issue assessment extracts GitHub issue references from the PR body. The Worker fetches issue text, checks change scope, and adds the model usage to the review record. walkthrough.show_linked_issues controls display, while assess_linked_issues controls the assessment itself.

walkthrough.calm (default false) is a quiet-first preset for noisy repositories: when true, every optional walkthrough section — changed files, review effort, the architecture diagram, pre-merge checks, related PRs, review details, the AI-agent prompt, and linked issues — is hidden unless that specific flag is also explicitly set to true. The verdict, findings, and walkthrough summary always render.

PR history stores recent merged summaries by repository. max_count selects how many recent entries enter the prompt.

learning.collect_merge_reactions (default false) enables the per-merge read of 👍/👎 reactions on bot review comments. Reply sentiment, review dismissals, and applied autofixes feed the learning loop regardless of this setting; enable it only for repositories where maintainers actually react to findings.

Walkthrough, description, and labels

walkthrough:
  collapsed: true
  calm: false
  show_changed_files: true
  show_effort: true
  show_architecture_diagram: true
  show_pre_merge_checks: true
  show_related_prs: true
  show_review_info: true
  show_ai_agent_prompt: true
  show_linked_issues: true

summarize:
  enabled: false

auto_describe: false

labels:
  - path: "src/**/*.ts"
    label: typescript
  - path: "apps/dashboard/**"
    label: dashboard

Top-level labels adds GitHub labels based on changed path globs. This is different from auto_review.labels, which gates automatic review.

walkthrough.show_architecture_diagram controls the evidence-backed Mermaid diagram inside the architecture-impact section. The diagram appears only when the bounded TypeScript or JavaScript graph has at least two observed import or likely-test relationships. Diagram node IDs, ordering, and graph fingerprints are deterministic for the same evidence and reviewed head.

summarize.enabled prepends an AI summary to the existing PR body after a completed review. auto_describe generates a description only for a newly opened PR with a short or missing body. auto_review.auto_describe is an accepted alias in the automatic-review block.

Suggested reviewers

suggested_reviewers:
  enabled: true
  auto_assign: true
  rules:
    - instructions: "Authentication and session changes"
      paths: ["src/auth/**", "src/session/**"]
      reviewers:
        - handle: security-team
          type: team
        - handle: alice
          type: user

Each rule needs instructions and at least one reviewer. type defaults to user; team uses GitHub team review requests. Matching suggestions appear in the walkthrough. auto_assign sends the GitHub review request. When no enabled rule matches, the reviewer falls back to matching entries in .github/CODEOWNERS; auto_assign: true requests those CODEOWNERS owners too, even if enabled remains false.

SAST and AST rules

SAST exclusions

sast:
  exclude_paths:
    - "eval/**"
    - "scripts/release.cjs"

The effective exclusion list combines:

• built-in test, spec, fixture, mock, example, and .github/workflows patterns;
• ignore_paths;
• custom sast.exclude_paths.

Built-in regex rules inspect added lines for credentials, private keys, GitHub and model tokens, database URLs, SQL or shell interpolation, DOM XSS sinks, eval, new Function, exec calls built from input, debug statements, silent promise catches, HTTP dependency URLs, one auth-bypass pattern, and process-exit cleanup bypasses.

AST rules

ast_rules:
  - id: no-console-log
    message: Use the application logger instead of console.log.
    severity: warning
    paths: ["src/**"]
    languages: [typescript, javascript]
    node_type: CallExpression
    callee: console.log

  - id: no-legacy-import
    message: Import the new client package.
    severity: critical
    node_type: ImportDeclaration
    import_source: legacy-client

Fields:

Field	Required	Notes
id	yes	Stable ID, up to 80 safe characters
message	yes	Finding text, up to 500 characters
severity	no	warning by default, or critical
node_type	yes	Babel AST node name
paths	no	Exact paths or globs, up to 20
languages	no	typescript and/or javascript; both by default
callee	no	Dotted name such as console.log
argument	no	Literal or dotted argument value that must occur
import_source	no	Exact ImportDeclaration module source
decorator	no	Decorator name, including called decorators

Rules run only against added JavaScript or TypeScript nodes. The parser does not execute repository code. At most 50 valid rules are retained per config layer, and duplicate IDs in one layer are dropped.

deterministic_pre_checks.enabled controls built-in metadata checks that run before model analysis. It does not disable SAST.

Test-generation instructions

test_generation:
  path_instructions:
    - path: "src/api/**"
      instructions: "Write Vitest request tests with mocked GitHub responses."
    - path: "apps/dashboard/**"
      instructions: "Use Testing Library and assert loading and error states."

Matching instructions are supplied to test generation for the affected paths.

Slop detection and telemetry

slop_detection:
  enabled: true
  label: slop

delta_review:
  enabled: false
  max_files: 300

telemetry:
  enabled: true

Slop detection scans added text and can add the configured label. Delta re-reviews (default off) re-review only the files changed since the last reviewed SHA on synchronize pushes, falling back to a full review whenever the delta is empty, oversized, or on a divergent history; enable per repo after validating the behavior. Telemetry controls model and usage display in the review output. Review logs still retain operational data needed for the dashboard when telemetry display is off.

Private recall sample

shadow_recall runs a second, private review after the public filters finish. It never posts a comment, changes a check conclusion, or trains learning rules. The dashboard stores its candidate count and up to 20 candidates that were absent from the public review. It is disabled by default; enable it per repository with enabled: true. It samples sampling (0-1, default 0.1) of eligible reviews; set sampling: 1 to sample every review or sampling: 0 to disable the pass while keeping the setting visible. Set an expiry date when raising the sample rate, then remove the setting after the sample window. Set an expiry date when raising the sample rate, then remove the setting after the sample window.

shadow_recall:
  enabled: true
  expires_at: "2026-07-31T23:59:59Z"
  max_diff_chars: 75000
  sampling: 0.1

Pull requests with a larger diff record diff_too_large, and reviews outside the sample rate record sampling, without making the extra model call.

Full example

tone: assertive

auto_review:
  enabled: true
  drafts: false
  base_branches: [main, "release/.*"]
  labels: ["!wip"]
  test_review_mode: lightweight

ignore_paths:
  - "**/generated/**"

noise:
  min_severity: warning
  max_findings: 12

path_rules:
  - id: api-auth
    path: "src/api/**"
    severity: critical
    rules:
      - "Every route must verify the caller before reading repository data."

external_context:
  files: [docs/api-contract.md]
  max_chars: 10000

pre_merge_checks:
  block_secrets: true
  require_tests: true
  require_description: true
  min_description_length: 80
  custom_checks:
    - "Public response fields remain backward compatible."

check_run:
  blocking_severities: [critical, warning]

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

Linear task context

linear_context: true (default) enables optional task lookup only when the operator has configured an exact repository entry in LINEAR_REPOSITORY_CREDENTIALS. Set it to false to disable lookup and the advisory model request. The base-branch configuration controls this setting. walkthrough.show_linked_issues controls whether its output appears in the review.

The reviewer extracts up to three task identifiers from the title, description, and branch. It fetches task links, descriptions, state, and explicit relationships, then searches for up to three possible matches within the allowed teams and, when available, the linked tasks' projects. Search matches are labelled as unconfirmed. The integration reads Linear; it does not create tasks, add comments, or change status.

Lookup starts alongside repository context preparation, has a four-second network budget, and caches scoped task data for five minutes. An optional advisory model request runs beside the code review. Posting reads the available results without waiting for either operation; unavailable/pending context is shown honestly. A fast review may finish before recommendations are ready. Rerun to refresh them.

Advisories suggest acceptance-criteria checks, unfinished dependencies, possible work overlap, and existing bug references. Each recommendation must cite an exact quote from a fetched task. They never change the verdict, validation, severity, or blind-first primary prompt. Task status is not evidence of deployment or acceptance.

For a complete review with findings and an explicitly linked task, the section also offers up to three prefilled Linear draft links. Open these only for findings you accept and deliberately defer, after checking for an existing task. The user must submit the Linear form to create a task; doing so does not resolve a finding or bypass a merge gate.

Operator rate limits (environment)

• RATE_LIMIT_MAX — max bot commands per commenter per window (default 20).
• RATE_LIMIT_WINDOW — window length in seconds (default 3600).
• Unauthenticated token endpoints (/api/cli/auth/exchange, /api/tenants/claim) are additionally capped at 30 requests per minute per IP.