Configuring Cerbie for a repository

Cerbie reviews every pull request in repositories where the Cerbie GitHub App is installed. It works with no configuration at all. Everything in this guide is optional and lives in a .cerbie/ directory in the repository being reviewed, so anyone who can open a PR can improve how their project is reviewed.

.cerbie/
├── config.yaml          # settings: triggers, ignored paths, review profile, approvals
├── instructions.md      # always-on guidance for reviewing this repository
├── rules/               # guidance scoped to paths (one topic per file)
│   └── api-handlers.md
└── checks/              # custom checks: each file becomes its own GitHub check run
    └── migration-safety.md

apps/billing/.cerbie/instructions.md   # nested instructions apply to apps/billing/** only

How Cerbie decides what to say

Three layers of guidance are combined for every review:

The Cerbie review policy (in the Cerbie repository, apps/worker/src/review/prompts/policy.md). This holds the organisation-wide standards: what counts as critical, the evidence a finding needs and when to ask for tests. Change it with a PR to lleverage-ai/cerbie.
Organisation instructions, edited by Cerbie admins in the dashboard (Settings).
Repository guidance: everything in this guide, plus the convention files your coding agents already read:
- AGENTS.md, AGENT.md and CLAUDE.md, at the root and in any directory above a changed file
- .cursor/BUGBOT.md, at the root and nested
- .github/copilot-instructions.md
- .github/instructions/*.instructions.md, honouring applyTo. Files with excludeAgent: code-review are skipped.

Repository guidance can add standards and context. It cannot switch off the review policy’s safety rules. For example, it cannot tell Cerbie to approve without reviewing.

`config.yaml`

Every key is optional. This shows all keys with their defaults:

version: 1

reviews:
  enabled: true            # false turns Cerbie off for this repository
  auto_review: true        # review on open and push; when false, only on `@cerbieai review`
  drafts: false            # review draft PRs automatically
  base_branches: []        # globs of base branches to review; empty = default branch only
  ignore_authors: ["dependabot[bot]", "renovate[bot]"]
  ignore_labels: ["cerbie:skip"]
  ignore_title_patterns: ["^\\[?WIP\\]?\\b", "^DO NOT MERGE"]
  debounce_seconds: 15     # wait this long after a push before reviewing, to batch pushes

paths:
  ignore: []               # globs Cerbie does not review (still listed in the summary)
  risk:                    # globs that always get a deep review with a security pass
    - pattern: "apps/app/src/server/auth/**"
      reason: authentication

summary:
  enabled: true            # post the sticky summary comment
  walkthrough: true
  diagrams: auto           # auto | always | never
  description: "off"       # off | append (managed block at the end) | placeholder (replaces "@cerbieai summary")

review:
  profile: balanced        # chill | balanced | assertive
  block_on: should_fix     # critical | should_fix | never: which findings request changes; the rest approve with comments
  min_confidence: 80       # findings below this confidence are dropped
  max_suggestions: 3       # optional suggestions per review
  language: en-GB
  ticket:
    enabled: true          # read the linked Linear ticket and check requirements
    pattern: "\\b[A-Z][A-Z0-9]+-\\d+\\b"

approval:
  mode: approve            # approve: submit GitHub approvals; comment: never approve
  trusted_authors: []      # authors whose PRs Cerbie may approve at any size (empty = everyone)
  human_approval_line_limit: 1001  # untrusted authors at or above this many changed lines need a human

checks:                    # built-in deterministic checks (no LLM, no installs)
  dependencies: true       # new npm packages: existence, age, deprecation, licence, unpinned sources
  lockfile: true           # dependency changes without a lockfile update
  secrets: true            # high-confidence credential patterns in added lines
  migrations: true

context:
  guidelines: ["AGENTS.md", "AGENT.md", "CLAUDE.md", ".cursor/BUGBOT.md", ".github/copilot-instructions.md"]

Lockfiles are never reviewed line by line. Unknown keys are reported rather than silently ignored: a typo shows up in the review’s coverage section and in @cerbieai config.

Review profiles

Profile	Reports
`chill`	Critical issues and clearly important should-fix issues; suggestions rarely.
`balanced`	Verified critical and should-fix issues, and a few valuable suggestions.
`assertive`	Every verified should-fix issue and up to three suggestions. Small PRs still get a full (non-light) pass.

`instructions.md`

Plain markdown that every review of this repository reads. Write it for a senior engineer joining the project who needs to review a PR tomorrow: what matters here, what tends to go wrong, and which conventions are deliberate.

# Reviewing the Lleverage app

- Every tRPC procedure that reads organisation data must go through `organisationProcedure`;
  a plain `protectedProcedure` on org data is a critical authorisation bug.
- Money is stored as integer cents. Floats anywhere in billing are a should-fix.
- We deliberately use `void promise` for fire-and-forget analytics; do not flag it.

Good instructions are specific, testable and explain why. Avoid style preferences that a linter could enforce: put those in the linter.

Nested instructions: apps/billing/.cerbie/instructions.md applies only when files under apps/billing/ change. This keeps area-specific knowledge next to the code it describes.

`rules/*.md`: guidance scoped by path

Use rules for guidance that only applies to some files. The frontmatter paths (or applyTo, for Copilot compatibility) takes globs:

---
description: tRPC handlers
paths: ["apps/app/src/server/api/routers/**/*.ts"]
---
- Input must be validated with zod at the procedure boundary.
- Never return Prisma models directly; map them to an API type so new columns don't leak.

A rule is included in a review only when at least one changed file matches its paths.

`checks/*.md`: custom checks

A check is a rule your team wants enforced on every relevant PR and reported separately, such as “migrations must be backwards compatible” or “new endpoints must have rate limiting”. Each check file becomes its own GitHub check run named Cerbie: <title>, so you can see at a glance which policies pass, and make important ones required in branch protection.

---
title: Migration safety
description: Database migrations must be safe to deploy while old code is running
include: ["packages/db/prisma/migrations/**"]
exclude: []
severity: critical        # severity of each violation: critical | should_fix | suggestion
conclusion: failure       # check-run conclusion when violated: neutral (default) | failure
enabled: true
---
Fail when a migration:
- drops or renames a column or table that the currently deployed code still reads;
- adds a NOT NULL column without a default to an existing table;
- creates an index on a large table without `CONCURRENTLY`.

Pass when the migration is additive, or when the PR description explains the multi-step rollout.

Field	Default	Meaning
`title`	file name	Check-run name (max 60 characters).
`description`	—	One line shown in the dashboard.
`include`	`["**"]`	Globs of files the check applies to. The check runs only when a changed file matches.
`exclude`	`[]`	Globs to leave out.
`severity`	`should_fix`	Severity of each violation in the review.
`conclusion`	`neutral`	`neutral` reports problems without blocking. `failure` fails the check run, which blocks merging if the check is required in branch protection.
`enabled`	`true`	Set to `false` to switch a check off without deleting it.

Write the body as pass/fail criteria. Checks are for team policy. Don’t duplicate general bug-finding, which every review already does.

Built-in behaviour worth knowing

Incremental reviews. After the first review, Cerbie reviews only what changed since the last reviewed commit. It re-checks its earlier findings and lists fixed ones in the new review. Earlier comments are never edited and threads are left for the PR author to resolve; if someone replied on a fixed finding’s thread, Cerbie adds a “✅ Addressed in abc1234” reply there. A force-push triggers a full review. Before each incremental review, a cheap check (no model call) decides whether a full review is needed instead:
- the merge base moved (base branch merged in, or a rebase);
- this repository’s review rules (.cerbie/, guidelines, org instructions) changed;
- the PR now needs a deeper review or a specialist (security, data, contracts) it hasn’t had;
- the new commits change at least half the PR’s lines;
- this would be the sixth incremental review in a row;
- the last full review is more than three days old.
If the new commits change exports that unchanged PR files import, those files are reviewed too, or the whole PR if there are more than 15. The review says when and why its scope changed. @cerbieai full review always reviews everything.
Independent verification. Candidate findings are challenged by a separate verifier, in a fresh context, before they are posted. Unverifiable findings are dropped.
No builds or tests. Cerbie does not install dependencies, compile or run tests. Your CI does that, and Cerbie reads its status. Cerbie spends its time on behaviour, security, data and contracts.
Replies. Reply to any Cerbie comment. Your reply is context for a focused re-review of that finding: Cerbie checks your claims against the code and replies with its conclusion. It withdraws a finding that doesn’t apply, confirms one you’ve fixed, or upholds it with evidence. For should-fix findings and suggestions it can also accept a reasoned deferral, such as a linked follow-up ticket or a sound scope decision. A bare “won’t do” doesn’t clear anything, and a critical clears only if it’s shown wrong or fixed. The same bar applies to everyone; maintainers who want to merge past Cerbie do so through their own merge rules. A top-level @cerbieai comment can address several findings at once. Findings Cerbie withdrew or deferred aren’t raised again unless they come back more severe, and a review filtered by one PR’s decisions is never reused for another PR. Resolving the thread is left to you and is just housekeeping: it doesn’t clear the finding.
Opting out. Add the cerbie:skip label, or put cerbie: skip on its own line in the PR description.

Commands

Comment	Effect
`@cerbieai review`	Review new commits now (incremental).
`@cerbieai full review`	Review the whole PR again from scratch.
`@cerbieai pause` / `@cerbieai resume`	Stop or restart automatic reviews on this PR.
`@cerbieai resolve`	Close all Cerbie threads. Tidying up only: it doesn’t clear findings or change the verdict.
`@cerbieai config`	Show the effective configuration and any problems with it.
`@cerbieai help`	List commands.
`@cerbieai <question>`	Ask anything about the PR; Cerbie answers with the code in hand.

Commands are accepted from the PR author and from organisation members or collaborators.

Verdicts

Like a human reviewer, Cerbie either approves or requests changes; there is no in-between.

Verdict	When	GitHub effect
✅ Approved	No open findings	Approval
✅ Approved with comments	Only non-blocking findings (below `block_on`; suggestions never block)	Approval, with the findings as comments
🔴 Changes requested	An open blocking finding (`block_on`, default critical and should-fix)	Request changes
⚪ Review incomplete	A required review stage failed and nothing blocking was found	Comment; never an approval

The fast path to approval. A block clears once Cerbie has cleared every blocking finding: after a push (the incremental review re-checks earlier findings) or after a reply it agrees with. When the change comes from discussion, Cerbie re-reviews only the findings in question, not the whole PR. If that leaves nothing blocking, it posts an approval and dismisses its earlier “changes requested”. Approvals still follow the approval settings below.

The Cerbie (Review) check run mirrors the verdict: failure for changes requested, neutral for incomplete, success otherwise. Make it a required check to gate merging on Cerbie.

Learnings

Cerbie also learns from the team. When a developer explains in a thread why a finding doesn’t apply, and Cerbie agrees and withdraws it, Cerbie can record the general fact behind it as a learning for that repository. You can also teach it directly with @cerbieai remember <fact>, or add a learning in the dashboard.

Learnings from people with write access take effect immediately. Others are proposed and wait for approval on the dashboard’s Learnings page, where anyone signed in can approve or reject them and admins can delete them. Approved learnings are included in every future review of the repository, and organisation-wide ones in every review.

Facts that belong in version control (conventions, architecture) are better added to .cerbie/instructions.md or .cerbie/rules/ in a PR, so they are reviewed like code. Learnings are for the small, discovered facts that would otherwise be lost in PR threads.