Skip to main content
A .coderabbit.yaml file at the root of your repository is the version-controlled way to configure CodeRabbit. Changes go through code review, keep history, and deploy with your code. It is the recommended approach for most teams.

Add the file to your repository

Create the file in the root of the repository. Hosted reviews read the file from the branch your configuration source selects. .coderabbit.yaml and .coderabbit.yml behave the same. A YAML file always wins over the TypeScript configuration. Local reviews look for more names: the CLI and the JetBrains plugin also find coderabbit.yaml and coderabbit.yml, and the VS Code extension also finds .coder.yaml. CodeRabbit applies only the names in the table above, so a review that finds one of these extra names uses no repository file. See Configuration in CLI and IDE reviews.

Choose a schema version

CodeRabbit picks the configuration schema after it picks the file. Existing files never migrate on their own. A schema URL comment in the file doesn’t select a version.
V3 is a limited preview. Adding version: 3 to a file doesn’t give your organization access. A file with version: 3 fails validation, and CodeRabbit uses the next layers. Keep using V2.
When a file fails to parse or has a wrong value type, CodeRabbit drops the file for that review and uses the next layers: central configuration, web interface settings, then defaults. The pull request summary starts with a parsing warning. Unknown V2 keys don’t fail the review; the summary lists them as unrecognized properties. V3 treats unknown keys as errors.

File structure

The two versions share language and inheritance and differ in everything else.
.coderabbit.yaml
V2 has ten top-level keys and a flat reviews object. V3 has version, language, inheritance, reviews and fun, and groups reviews into behavior, auto_review, output and tools. Path instructions and custom checks live in the configuration directory (.coderabbit/), and settings such as the Knowledge Base and chat integrations are managed outside the review YAML. The settings map lists each setting with its V2 key, web label and V3 key. To move a file, follow Migrate configuration to V3. For every key, see the V2 configuration reference and the V3 configuration reference.

Get editor autocomplete and validation

Put the schema comment on the first line of the file. Editors that use the YAML language server then autocomplete keys and flag mistakes.
.coderabbit.yaml
CodeRabbit writes this line itself into new files from the web interface and from @coderabbitai generate configuration.
The published V2 schema has no version property and rejects unknown top-level keys. An editor flags version (including version: 2) and remote_config, although CodeRabbit accepts both at review time. See Validate and test a configuration change.

Move settings from the web interface into the file

1

Print the resolved configuration

Comment @coderabbitai configuration on any pull request. CodeRabbit replies with YAML and a comment on each setting that names its source.
2

Copy it into the file

Paste the YAML into .coderabbit.yaml at the repository root. You can also copy the YAML from the YAML editor view mode in the web interface.
3

Open a pull request

With the default Configuration source, a pull request that a repository member opens from a branch in the same repository is reviewed with the file it adds. Fork pull requests use the file from the base commit, and a Custom branch always supplies the file from that branch. See Choose the configuration branch. See Validate and test a configuration change.
The resolved output uses runtime setting names and can include values from other layers. It isn’t a V3 migration file.

What’s next

Instruction and check documents

Keep instructions and checks in Markdown under .coderabbit/.

Choose the configuration branch

Decide which branch reviews read the file from.

Validate and test a change

Catch mistakes before they reach a review.