Skip to main content
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.

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

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.

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.

Where each layer sits

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

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.

What happens when something fails

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

Inheritance and merging

Learn how the inheritance walk stops and how each mechanism merges values.

Check which configuration a review used

Print the resolved configuration and read the layer behind each value.

Fix settings that aren't applied

Work through the common reasons a setting doesn’t reach a review.