Concepts

Code review reads one config file from your repo, fetches each pull request’s diff, runs an AI reviewer over it, and posts the results back to the PR. This page covers the mental model so the configuration choices make sense.

What it is

A reviewer that comments on your pull requests the way a thorough teammate would — but configured by a file in your repo, scoped to your conventions, and consistent on every PR. It does three things on each review:

1. A summary — a top-level walkthrough comment that says what the change does and what’s worth a closer look.
2. Inline comments — per-hunk comments on the exact lines that need attention, batched into a single PR review so your notifications don’t explode.
3. A Check — a “Destesi Review” entry in the Checks tab that can gate merges when findings are severe.

The mental model

Config is policy, committed to main

The reviewer reads .destesi.yml from your repo’s default branch, never from the branch under review. This is the single most important thing to understand.

If the PR-branch version were honoured, a contributor could, in the same change they want approved:

• add an instruction telling the reviewer to “always approve everything in src/auth/”;
• delete a rule just in time to slip a finding past the bot;
• loosen who is allowed to run chat commands.

Reading from the default branch turns .destesi.yml into a policy your team agreed to on main. A PR that edits the file is reviewed under the rules currently on main, and the edit itself shows up as a normal part of the diff to review.

Tip

This is the inverse of how Preview reads its config. Preview reads .destesi.yml from the PR branch, because “what the PR proposes is what gets deployed.” Code review reads from the default branch, because “what main agreed to is the policy.” Same file, two products, two deliberate read-sources.

Triggers say when, scope says which

Two independent filters decide whether a given file gets reviewed:

• Triggers — when the reviewer acts: on PR open, on every push, or only when asked via a chat command.
• Scope — which PRs and which files within them are eligible: drafts, base branches, and include/exclude path globs.

A file is reviewed only when a trigger fired and the file is in scope. Ignored paths (from defaults.ignore.paths or scope.paths.exclude) always win over inclusion.

Instructions are how it learns your codebase

The default reviewer does solid generic-judgement work. Per-path instructions are how it learns your rules — “wrap errors with %w”, “never add a control-plane route without auth middleware”, “this directory is generated, don’t nit it.” Each instruction is a { paths, guidance } pair; multiple matches stack in declaration order, so broad rules and surgical rules compose. This is the highest-leverage knob in the whole config — see Reference.

The Check is the gate, not the verdict

The reviewer submits its findings as plain PR comments — never as a formal GitHub “Approve” or “Request changes” that sits in a human reviewer’s seat. Gating is the Check’s job: with the default fail_check_on: severe, the “Destesi Review” Check goes red only when there’s a severe finding, so it can be a required status check without blocking on taste-level nits. (One exception: with approve_on: clean, a review that finds nothing submits a lightweight Approve event — see Reference.)

Two passes, two model choices

Each review is a fan-out of one call per changed file (the inline pass) plus one call total for the summary. Because the inline pass is the expensive part on a large PR, you can pick a cheaper model for it and a stronger model for the single summary call. Omit the model block entirely to use the platform defaults.

The review lifecycle

Every review moves through a small state machine, visible on the dashboard:

queued → fetching_config → reviewing → publishing → done
                                                  ↘ failed

• queued — the PR event landed; the review is waiting to be picked up.
• fetching_config — reading .destesi.yml from the default branch.
• reviewing — fetching the diff and running the model passes.
• publishing — posting the Check, summary, and inline comments to GitHub.
• done / failed — terminal. A failed review carries an error message on the dashboard row.

Per-file failures are soft: if one file’s review call fails, that file is dropped (reported as review_failed in the summary’s “skipped files” footer) and the rest of the review continues. A failure to fetch the diff or run the summary fails the whole review.

How it fits the suite

Destesi is a suite of peer products unified by one login and one workspace. Code review is one of them:

• One workspace. Reviews are scoped to the workspace that owns the GitHub connection. Your teammates see the same reviews on the dashboard. See Workspaces.
• One sign-on. You reach the dashboard with the same account and SSO session you use for every other Destesi product.
• GitHub connected once. The GitHub credential the reviewer uses is added once per workspace in Connect and fetched at review time — it is never stored inside the review product. The same connection powers Preview.

Next

ReferenceFull .destesi.yml schema, chat commands, and env.

TroubleshootingWhy a review didn't fire and how to fix it.