> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coderabbit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration file

> Add a .coderabbit.yaml file to your repository, pick the configuration schema version, and get editor autocomplete and validation.

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](https://docs.coderabbit.ai/configuration/branch.md) selects.

| File present | File used |
| - | - |
| `.coderabbit.yaml` | `.coderabbit.yaml` |
| `.coderabbit.yml` | `.coderabbit.yml` |
| Both YAML names | `.coderabbit.yaml` |
| `.coderabbit.config.ts` only | `.coderabbit.config.ts` |
| A YAML file and `.coderabbit.config.ts` | The YAML file |

`.coderabbit.yaml` and `.coderabbit.yml` behave the same. A YAML file always wins over the [TypeScript configuration](https://docs.coderabbit.ai/configuration/typescript.md).

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](https://docs.coderabbit.ai/configuration/local-reviews.md).

## Choose a schema version

CodeRabbit picks the configuration schema after it picks the file.

| File content | Version used |
| - | - |
| No `version` field | V2 |
| `version: 2` | V2 |
| `version: 3` | V3, in the limited preview |
| `version: "3"` or another non-number | Version error |
| Any other number | Error: version not supported |

Existing files never migrate on their own. A schema URL comment in the file doesn't select a version.

> [!WARNING]
>
> 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.

> [tab] YAML V2
>
> ```yaml .coderabbit.yaml theme={null}
> language: en-US
> tone_instructions: ""
> early_access: false
> inheritance: false
> reviews:
>   profile: chill
>   path_instructions: []
> chat:
>   auto_reply: true
> knowledge_base: {}
> ```

> [tab] YAML V3
>
> Early Access (This feature is in early access. Enable it by setting `early_access: true` in your `.coderabbit.yaml`, or by toggling Early Access on the web interface.)
>
> V3 is a limited preview. Adding `version: 3` doesn't give your organization access.
>
> ```yaml .coderabbit.yaml theme={null}
> version: 3
> language: en-US
> inheritance: false
> reviews:
>   behavior:
>     profile: chill
>   auto_review: {}
>   output: {}
>   tools: {}
> fun:
>   tone_instructions: ""
> ```

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.

| V2 settings | Place in V3 |
| - | - |
| `tone_instructions` | `fun.tone_instructions` |
| `reviews.profile`, `reviews.path_filters` and automatic approvals | `reviews.behavior` |
| `reviews.auto_review` | `reviews.auto_review` |
| Summary and walkthrough settings | `reviews.output` |
| `reviews.tools` | `reviews.tools` |
| `reviews.path_instructions` and custom pre-merge checks | Markdown documents in `.coderabbit/` |
| `early_access`, `knowledge_base`, chat integrations, finishing touches and other owner settings | Outside the review YAML |

The [settings map](https://docs.coderabbit.ai/configuration/settings-map.md) lists each setting with its V2 key, web label and V3 key. To move a file, follow [Migrate configuration to V3](https://docs.coderabbit.ai/configuration/guides/migrate-to-v3.md). For every key, see the [V2 configuration reference](https://docs.coderabbit.ai/reference/configuration.md) and the [V3 configuration reference](https://docs.coderabbit.ai/reference/configuration-v3.md).

## 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.

```yaml .coderabbit.yaml theme={null}
# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
```

CodeRabbit writes this line itself into new files from the web interface and from `@coderabbitai generate configuration`.

> [!WARNING]
>
> 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](https://docs.coderabbit.ai/configuration/guides/validate-and-test.md).

## 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](https://docs.coderabbit.ai/configuration/branch.md). See [Validate and test a configuration change](https://docs.coderabbit.ai/configuration/guides/validate-and-test.md).

The resolved output uses runtime setting names and can include values from other layers. It isn't a V3 migration file.

## What's next

> [card] [Instruction and check documents](https://docs.coderabbit.ai/configuration/documents.md)
>
> Keep instructions and checks in Markdown under `.coderabbit/`.

> [card] [Choose the configuration branch](https://docs.coderabbit.ai/configuration/branch.md)
>
> Decide which branch reviews read the file from.

> [card] [Validate and test a change](https://docs.coderabbit.ai/configuration/guides/validate-and-test.md)
>
> Catch mistakes before they reach a review.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.