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:- The repository file from step 2.
- The central configuration file in the
coderabbitrepository. - Repository settings in the web interface, only while the repositoryâs Use organization settings toggle is off.
- Organization defaults, or workspace settings when the organization has no saved settings or has Use workspace settings on.
- Schema defaults.
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. Withinheritance: 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_CONFIGand 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.
What happens when something fails
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.