> ## 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 CodeRabbit resolves configuration

> Follow the steps CodeRabbit takes to build the one configuration a review uses, from choosing the file revision to applying global overrides.

Before each review, CodeRabbit builds one resolved configuration. It doesn't merge every place you configured: it picks one starting layer, adds parent layers only when inheritance is on, and then applies the layers that always win or always fill gaps. The steps below run in this order on every review.

```mermaid theme={null}
flowchart TD
  A["Review starts"] --> B{"1. Trusted pull request?"}
  B -- "Yes" --> C["Read files at the pull request head"]
  B -- "No, or the check fails" --> D["Read files at the pull request base commit"]
  C --> E["2. Select the repository file"]
  D --> E
  E --> F["3. Choose the starting layer"]
  F --> G{"4. Inheritance on?"}
  G -- "Yes" --> H["Merge parent layers"]
  G -- "No" --> I["5. Apply global overrides"]
  H --> I
  I --> J["6. Fill empty keys from workspace settings, then schema defaults"]
  J --> K["7. Apply per-review overrides, then global overrides again"]
  K --> L["Resolved configuration"]
```

## 1. Decide which revision to read

For a pull request, CodeRabbit reads configuration files at the pull request head only when the pull request is trusted: it comes from a branch in the same repository, not a fork, and its author meets your Git provider's [trust rule](https://docs.coderabbit.ai/configuration/branch.md#who-counts-as-trusted). Fork pull requests, other authors and failed lookups read the files at the pull request's base commit. Events that aren't pull requests read the default branch.

## 2. Select the repository file

On GitHub Cloud, the repository's **Configuration source** can replace the revision from step 1 with the default branch or a named branch. Every other provider uses **Auto**. See [Choose the configuration branch](https://docs.coderabbit.ai/configuration/branch.md).

At that revision, the first file that exists wins: `.coderabbit.yaml`, then `.coderabbit.yml`, then `.coderabbit.config.ts`. Files are never merged with each other. If the YAML file contains only `remote_config`, CodeRabbit fetches the file it points to and uses that instead.

## 3. Choose the starting layer

CodeRabbit uses the first of these that exists and is valid:

1. The repository file from step 2.
2. The central configuration file in the `coderabbit` repository.
3. Repository settings in the web interface, only while the repository's **Use organization settings** toggle is off.
4. Organization defaults, or workspace settings when the organization has no saved settings or has **Use workspace settings** on.
5. Schema defaults.

On self-hosted CodeRabbit, the list is the repository file, the central file, `YAML_CONFIG`, then schema defaults.

## 4. Merge parent layers when inheritance is on

Without inheritance, the starting layer supplies every value and anything it leaves out falls to schema defaults. With `inheritance: true`, CodeRabbit walks down the layers below the starting layer and merges each one, stopping after a layer whose own `inheritance` isn't `true`. See [Inheritance and merging](https://docs.coderabbit.ai/configuration/inheritance-and-merging.md).

## 5. Apply global overrides

Organization global overrides merge on top of the result, then workspace global overrides. They apply whether or not inheritance is on. While an organization has **Use workspace settings** on, CodeRabbit skips its organization global overrides. See [Global overrides](https://docs.coderabbit.ai/configuration/global-overrides.md).

## 6. Fill empty keys

When **Use workspace settings as defaults** is on, workspace settings fill only the keys that are still empty. Schema defaults then fill everything else.

## 7. Apply per-review overrides

A configuration block in the pull request description or a `@coderabbitai review --with-config` comment changes the configuration for that review only. CodeRabbit applies global overrides again afterwards, so a per-review override can't change an enforced setting. See [Change settings for one pull request](https://docs.coderabbit.ai/configuration/guides/one-pull-request.md).

## Where each layer sits

From highest to lowest. The label is what `@coderabbitai configuration` prints in its `# Source:` comments.

| Layer | Where you set it | Label in the output | How it takes part |
| - | - | - | - |
| Workspace global overrides | Workspace settings | `Workspace global overrides` | Always merged on top |
| Organization global overrides | Organization defaults, **Global overrides** | `Organization global overrides` | Merged on top, except while the organization has **Use workspace settings** on |
| Repository file | `.coderabbit.yaml`, `.coderabbit.yml` or `.coderabbit.config.ts` | `Repository YAML` | Starting layer |
| Central configuration | `coderabbit` repository | `Central YAML` | Starting layer or parent |
| Environment YAML | `YAML_CONFIG` on self-hosted CodeRabbit | `Environment YAML` | Starting layer or parent |
| Repository settings | Web interface | `Repository UI` | Starting layer or parent, while **Use organization settings** is off |
| Organization defaults | Web interface | `Organization UI` | Starting layer or parent |
| Workspace settings | Web interface | `Workspace UI` | Parent, or stands in for Organization defaults |
| Workspace settings used as defaults | **Use workspace settings as defaults** | `workspace defaults` | Fills empty keys |
| Schema defaults | Built in | `defaults` | Fills everything else |

## CodeRabbit Cloud and self-hosted CodeRabbit

The steps above describe CodeRabbit Cloud. Self-hosted CodeRabbit runs a shorter version of them:

* It always uses **Auto** in step 2.
* Its layers are the repository file, the central file, `YAML_CONFIG` and schema defaults. It has no Repository settings, Organization defaults or workspace settings.
* It has no global overrides, so step 5 adds nothing, and step 6 fills empty keys from schema defaults only.

A self-hosted Git provider, such as GitHub Enterprise Server or self-managed GitLab, connected to CodeRabbit Cloud follows the full CodeRabbit Cloud order. See [Configuration on self-hosted CodeRabbit](https://docs.coderabbit.ai/configuration/self-hosted.md).

## What happens when something fails

| What fails | What CodeRabbit does |
| - | - |
| The repository file doesn't exist | Treats it as absent and moves to the next layer |
| The repository file has invalid YAML or a wrong value type | Skips the file, uses the next layer, and starts the review summary with a parsing-error warning |
| The central file is invalid | Ignores it, uses the next layer, and adds a warning to the summary |
| The saved **Configuration source** is unavailable | Uses **Auto** and adds a warning that names the configuration used |
| The merged result fails validation | Uses schema defaults and adds a warning |
| `remote_config` points to a missing or empty file, a repository outside the allowed owner, or a repository the access check refuses | Treats the repository file as invalid: uses the next layer and adds a parsing-error warning |

> [!WARNING]
>
> If CodeRabbit can't read a configuration file for another reason, such as a provider timeout or server error, it retries the review. The same applies to the file `remote_config` points to. When the retries fail, the review is dropped and nothing is posted to the pull request.

## What's next

> [card] [Inheritance and merging](https://docs.coderabbit.ai/configuration/inheritance-and-merging.md)
>
> Learn how the inheritance walk stops and how each mechanism merges values.

> [card] [Check which configuration a review used](https://docs.coderabbit.ai/configuration/guides/check-effective-configuration.md)
>
> Print the resolved configuration and read the layer behind each value.

> [card] [Fix settings that aren't applied](https://docs.coderabbit.ai/configuration/guides/troubleshoot.md)
>
> Work through the common reasons a setting doesn't reach a review.


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