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

# How configuration works

> Find the configuration path for your team's size, see which settings win, and learn how CodeRabbit builds the configuration a review uses.

CodeRabbit reviews code for everyone from a single developer with one repository to enterprises with hundreds of thousands of repositories and strict compliance rules. To serve all of them, its configuration goes deep: settings can live in the repository, in a shared repository, in the web app and across a whole workspace, and administrators can lock settings that no team can change.

The good news is that you probably need very little of it. The defaults give good reviews from the first pull request, and most teams never need more than a `.coderabbit.yaml` file in the repository.

## Start here

> [accordion] One repository or a small team
>
> Add a `.coderabbit.yaml` file to the repository, or use the web app if you prefer a UI. Set how strict reviews are, add your team's rules, and skip files that don't need review. A file is reviewed like code and makes it easy to try settings on a branch.
>
> Start with [Create your first configuration](https://docs.coderabbit.ai/configuration/quickstart.md).

> [accordion] Many repositories
>
> Set a baseline once instead of in every repository: in central configuration (A configuration file in a repository named coderabbit that applies to every repository in your organization that has no configuration file of its own.), reviewed like code, or in **Organization defaults** in the [web app](https://docs.coderabbit.ai/configuration/web-app.md). Repositories without a file of their own use it automatically, including new ones. If a team later adds a `.coderabbit.yaml` to its repository, that file replaces the baseline for that repository. To keep the baseline and change only a few values, the file turns on inheritance (A setting that merges configuration values across multiple levels — repository YAML, central YAML, and UI settings — instead of using only the highest-priority source.) with `inheritance: true`. Several organizations under one SSO workspace can share workspace settings.
>
> See [Apply settings to every repository](https://docs.coderabbit.ai/configuration/guides/all-repositories.md).

> [accordion] Settings teams must not change
>
> Use global overrides (Settings an administrator pins for a whole organization or workspace in the web app. They replace the same settings from every other place, so repositories can't change them.). They replace the same settings from every other place, including a repository's own file. To also stop a pull request from changing how it's reviewed, on GitHub Cloud pin the branch CodeRabbit reads the configuration from.
>
> See [Enforce settings teams can't change](https://docs.coderabbit.ai/configuration/guides/enforce.md).

> [accordion] Self-hosted CodeRabbit
>
> Set instance-wide defaults with the `YAML_CONFIG` environment variable. Repository files and central configuration work as on CodeRabbit Cloud; the web app settings don't exist.
>
> See [Configuration on self-hosted CodeRabbit](https://docs.coderabbit.ai/configuration/self-hosted.md).

## Which settings win

When several places set the same setting, CodeRabbit starts from the first of these that exists: the repository's own file, central configuration, the repository's web settings, then Organization defaults. It doesn't combine them unless inheritance is on. Global overrides then replace anything they set, and built-in defaults fill the rest. Each of these places is called a layer.

To see what a review used and where each value came from, comment `@coderabbitai configuration` on the pull request, or open **Run configuration** in the review's **Review info**.

## Common tasks

> [card] [Reduce review noise](https://docs.coderabbit.ai/configuration/guides/reduce-noise.md)
>
> Get fewer, more useful comments.

> [card] [Choose which files are reviewed](https://docs.coderabbit.ai/pr-reviews/which-files.md)
>
> Skip generated code, third-party code and other noise.

> [card] [Teach CodeRabbit your rules](https://docs.coderabbit.ai/pr-reviews/review-instructions.md)
>
> Add guidance for specific paths and conventions.

> [card] [Control when reviews run](https://docs.coderabbit.ai/pr-reviews/when-reviews-run.md)
>
> Choose branches, drafts, authors and incremental reviews.

> [card] [Check which configuration a review used](https://docs.coderabbit.ai/configuration/guides/check-effective-configuration.md)
>
> See each value and the layer it came from.

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

> [card] [Automate configuration](https://docs.coderabbit.ai/configuration/guides/automate.md)
>
> Read and change settings with the API, MCP server and CLI.

> [card] [Configuration reference](https://docs.coderabbit.ai/reference/configuration.md)
>
> Every setting, with its default.

## What you can configure

Some examples of what teams change:

* **How strict reviews are**, and the language and tone of comments. See [Review style](https://docs.coderabbit.ai/pr-reviews/review-style.md).
* **Your team's rules**, such as "every API endpoint checks authorization" for `src/api/**`. CodeRabbit also reads guideline files you already have, such as `AGENTS.md`. See [Review instructions](https://docs.coderabbit.ai/pr-reviews/review-instructions.md) and [Code guidelines](https://docs.coderabbit.ai/knowledge-base/code-guidelines.md).
* **Which linters and security scanners run**, and with which of your configuration files. See [Review tools](https://docs.coderabbit.ai/tools/index.md).
* **What the summary and walkthrough include.** See [Summaries](https://docs.coderabbit.ai/pr-reviews/summaries.md) and [Walkthroughs](https://docs.coderabbit.ai/pr-reviews/walkthroughs.md).
* **Checks a pull request must pass**, written in plain language. See [Pre-merge checks](https://docs.coderabbit.ai/pr-reviews/pre-merge-checks.md).
* **What context CodeRabbit uses**, such as learnings and linked issues. See [Knowledge Base](https://docs.coderabbit.ai/knowledge-base.md).

Most of these are settings with fixed values. Your rules are plain-language instructions. To compute settings, for example per base branch, use [TypeScript configuration](https://docs.coderabbit.ai/configuration/typescript.md).

## How CodeRabbit builds the configuration for a review

Each review uses exactly one configuration. CodeRabbit builds it in five steps:

**1. Pick the file revision**

CodeRabbit reads the repository file from a revision it trusts: the pull request branch or the base branch. (By default, a trusted pull request, from a branch in the same repository by an author your Git provider trusts, is reviewed with the configuration file on its own branch, so a change to the file applies before it merges. Other pull requests use the file from the base commit. For some projects, for example for security reasons, a pull request shouldn't change how it's reviewed. On GitHub Cloud, set Configuration source to Default branch and turn off Allow configuration changes from trusted PRs, or pin a Custom branch.)

**2. Choose the starting layer**

The highest layer that exists becomes the starting point, for example the repository file or central configuration.

**3. Merge parent layers**

Only when inheritance (Inheritance is off by default, so a review uses only the starting layer. It's on when the starting layer sets inheritance: true, in the file or with the Inheritance toggle under General, or leaves it blank while Use workspace settings as defaults is on. A global override with inheritance: true turns it on for every repository. CodeRabbit then merges the layers below in a fixed order: central configuration, web app settings, workspace settings. The closer layer wins for every key it sets. The walk stops after a layer with inheritance off, unless a global override forces it.) is on, CodeRabbit merges the layers below the starting layer into it.

**4. Apply global overrides**

Organization and workspace overrides replace whatever the earlier steps set.

**5. Fill unset keys**

Workspace defaults, then built-in defaults, fill every key that's still unset.

For every step in detail, see [How CodeRabbit resolves configuration](https://docs.coderabbit.ai/configuration/resolution.md).

## Compare every place settings can live

Platform and security teams often need the full picture: who can edit each place, whether changes are version-controlled, and what each place reaches.

> [accordion] Show the comparison table
>
> | Place | Who edits | Version-controlled | Scope | Platforms | Defaults or enforces | V3 |
> | - | - | - | - | - | - | - |
> | Web interface: Repository settings | Roles with write access to Repository settings: Admin and Member by default | No | One repository | CodeRabbit Cloud | Defaults; used only while the repository's **Use organization settings** toggle is off | Follows the organization's settings version |
> | Web interface: Organization defaults | Roles with write access to Organization settings: Admin by default | No | Every repository that uses Organization defaults | CodeRabbit Cloud | Defaults | Follows the organization's settings version |
> | `.coderabbit.yaml` | Anyone who can commit to the branch CodeRabbit reads | Yes | One repository | All Git providers; CodeRabbit Cloud and self-hosted CodeRabbit | Defaults; replaces lower layers unless inheritance is on | `version: 3`, limited preview |
> | `.coderabbit.config.ts` | Anyone who can commit to the branch CodeRabbit reads | Yes | One repository, used only when no YAML file exists | All Git providers; CodeRabbit Cloud and self-hosted CodeRabbit | Same as `.coderabbit.yaml` | `version: 3`, limited preview |
> | Configuration directory (`.coderabbit/`) | Anyone who can commit to the branch | Yes | The directory that holds it and everything below | GitHub Cloud with CodeRabbit Cloud | Adds instructions and checks; not a settings layer | Works with V2 and V3 |
> | Central configuration (`coderabbit` repository) | Anyone who can commit to the `coderabbit` repository | Yes | Repositories without their own file, and repositories whose file sets `inheritance: true` | GitHub, GitHub Enterprise Server, GitLab, Azure DevOps, Bitbucket Cloud, Bitbucket Data Center | Defaults; a repository file replaces it unless inheritance is on | V2 only |
> | `remote_config` | Anyone who can commit to the redirecting repository and the target | Yes for the repository form; no for the URL form | Each repository whose file redirects | All Git providers | Same as the repository file it replaces | Not supported |
> | Workspace settings | SSO workspace: workspace admins and Admins of any organization in the workspace. Self-hosted Git provider workspace: roles with write access to Organization settings | No | Organizations in the workspace | SSO workspaces and self-hosted Git provider workspaces on CodeRabbit Cloud | Defaults | Follows the workspace's settings version |
> | Global overrides | Organization: roles with write access to Organization settings. Workspace: the same people as workspace settings | No | Every repository in the organization or workspace | CodeRabbit Cloud | Enforces | V2 schema only |
> | `YAML_CONFIG` (Environment YAML) | Whoever operates the deployment | Depends on your deployment | Every repository on the instance | Self-hosted CodeRabbit only | Defaults below the repository and central files | V2 only |
>
> A form save in the web interface stores every value, including defaults you didn't change. A save from the **YAML editor** stores only the values you wrote. Stored values count as set, so after a form save, inherited Organization defaults can't change any single value in Repository settings. Only lists still combine. See [Why saved Repository settings can hide organization values](https://docs.coderabbit.ai/configuration/inheritance-and-merging.md#why-saved-repository-settings-can-hide-organization-values).

## Configuration schema V2 and V3

Configuration files use schema V2. Schema V3 is a limited preview that regroups the review settings and moves instructions and checks into Markdown documents. See [Migrate configuration to V3](https://docs.coderabbit.ai/configuration/guides/migrate-to-v3.md).

## Configuration and learnings

Learnings (Review preferences CodeRabbit learns from your chat conversations and applies automatically to future reviews.) are preferences CodeRabbit records when you chat with it on pull requests. They aren't a configuration layer: use configuration for documented standards and learnings for preferences that come up during review.

## What's next

> [card] [Create your first configuration](https://docs.coderabbit.ai/configuration/quickstart.md)
>
> Decide between the web app and a file, then set the five settings that matter most.

> [card] [Apply settings to every repository](https://docs.coderabbit.ai/configuration/guides/all-repositories.md)
>
> Share one baseline across an organization or workspace.

> [card] [How CodeRabbit resolves configuration](https://docs.coderabbit.ai/configuration/resolution.md)
>
> Follow each step CodeRabbit takes to build the configuration for a review.


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