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

# Inheritance and merging

> Turn on configuration inheritance, see which layers the inheritance walk merges, and compare how each CodeRabbit mechanism merges objects, arrays and values.

By default, the highest layer that exists supplies the whole configuration, and anything it leaves out falls to schema defaults. Inheritance lets a layer take the values it doesn't set from the layers below it. Several other mechanisms also combine configuration, and each one merges values differently.

## Turn on inheritance

> [tab] In the app
>
> Open the repository's settings, go to the **General** section, and turn on **Inheritance**. Repository settings take part only while the repository's **Use organization settings** toggle is off.

> [tab] YAML
>
> ```yaml .coderabbit.yaml theme={null}
> inheritance: true
> reviews:
>   profile: assertive
> ```

`inheritance` is a top-level key in both configuration schema V2 and V3. A `.coderabbit.config.ts` file uses the same key.

## When inheritance applies

The inheritance walk runs when any of these is true:

* The starting layer sets `inheritance: true`.
* The starting layer leaves `inheritance` blank and **Use workspace settings as defaults** is on.
* An organization or workspace global override sets `inheritance: true`. This beats every layer's own flag. A workspace override's `inheritance` value wins over the organization's. When an organization has **Use workspace settings** on, its organization overrides are ignored. See [Enforce settings](https://docs.coderabbit.ai/configuration/guides/enforce.md).

## How the inheritance walk works

The walk follows a fixed order below the starting layer: central configuration, then Repository settings, Organization defaults and workspace settings, then schema defaults. On self-hosted CodeRabbit, `YAML_CONFIG` takes the place of the web interface layers. CodeRabbit merges each parent it finds. It stops after a parent whose `inheritance` is `false`, or blank while **Use workspace settings as defaults** is off. When a global override sets `inheritance: true`, the walk doesn't stop and merges every layer. Missing layers are skipped.

```mermaid theme={null}
flowchart TD
  A["Repository YAML<br/>inheritance: true"] --> B["Central YAML<br/>inheritance: true"]
  B --> C["Organization defaults<br/>inheritance: false"]
  C -. "walk stops" .-> D["Workspace settings<br/>not merged"]
```

In this example the review gets values from the repository file, the central file and Organization defaults. Workspace settings aren't merged because Organization defaults has inheritance off.

### Parents for each starting layer

| Starting layer | Parents the walk can merge, in order |
| - | - |
| Repository file | Central configuration, Repository settings, Organization defaults, workspace settings |
| Central configuration | Repository settings, Organization defaults, workspace settings |
| Repository settings | Organization defaults, workspace settings |
| Organization defaults | Workspace settings |
| Workspace settings, standing in for Organization defaults | None |

A parent takes part only when it exists for the repository:

* Repository settings, while the repository's **Use organization settings** toggle is off.
* Organization defaults, when the organization has saved settings and **Use workspace settings** is off.
* Workspace settings, when the organization belongs to a workspace.

On self-hosted CodeRabbit, a repository file can merge central configuration and then `YAML_CONFIG`, and a central file can merge `YAML_CONFIG`. Schema defaults fill whatever is still unset after the walk.

### Why saved Repository settings can hide organization values

A form save in the web interface stores every value, including defaults you didn't change and the **Inheritance** toggle itself. When the walk reaches Repository settings saved this way, every value is already set, so Organization defaults and workspace settings can't change any single value below them. Only lists still combine. If **Inheritance** was off when you saved, the walk also stops there.

To let organization values through, save Repository settings from the **YAML editor** view mode, which stores only the values you wrote, or turn on the repository's **Use organization settings** toggle. See [Settings in the web app](https://docs.coderabbit.ai/configuration/web-app.md).

## How values merge

| Mechanism | Objects | Arrays | Scalars | Empty values |
| - | - | - | - | - |
| Inheritance | Merged key by key; the child wins | Child entries first, then parent entries whose key the child doesn't have | Child wins when set | An empty child array takes the parent array; a missing key takes the parent value |
| `mergeConfig` in TypeScript | Merged key by key; the later fragment wins | Concatenated in order, duplicates kept | Later fragment wins | A missing key never overwrites an earlier value |
| Global overrides | Merged key by key; the override wins | Override entries first, then base entries whose key the override doesn't have | Override wins | An empty override array leaves the base array unchanged |
| Workspace settings as defaults | Nested empty keys are filled | Only an empty or missing array takes the workspace array | Only a missing value is filled | `false`, `0` and `""` count as set and aren't replaced |
| Directory documents | Not merged field by field | Not merged field by field | Not merged field by field | A closer document with `enabled: false` turns off an inherited document with the same ID |

Arrays of objects are matched by the first of these fields they have: `path`, `label`, `name`, `id`, `key`, `repository`. Entries without any of them are matched by their whole content. For `path_instructions`, every inherited rule whose `path` the child doesn't redefine is kept.

Directory documents combine as whole documents. For each changed file, documents from the repository root and every enclosing `.coderabbit/` directory apply, and the closest document with the same kind and ID replaces the one above it.

## Example: merge a repository file with central configuration

The repository file turns on inheritance. The central file leaves `inheritance` blank, so the walk merges central configuration and stops there.

> [tab] Central
>
> ```yaml .coderabbit.yaml in the coderabbit repository theme={null}
> language: "en-US"
> reviews:
>   profile: chill
>   high_level_summary: true
>   auto_review:
>     enabled: true
>     drafts: true
>     labels:
>       - "!wip"
>   path_instructions:
>     - path: "src/**"
>       instructions: "Follow our coding standards."
>     - path: "docs/**"
>       instructions: "Check for grammar and clarity."
> chat:
>   art: false
> ```

> [tab] Repository
>
> ```yaml .coderabbit.yaml theme={null}
> inheritance: true
> language: "de-DE"
> reviews:
>   profile: assertive
>   auto_review:
>     drafts: false
>     labels:
>       - "!do-not-review"
>   path_instructions:
>     - path: "src/**"
>       instructions: "Use strict TypeScript settings."
>     - path: "api/**"
>       instructions: "Validate API contracts."
> ```

> [tab] Result
>
> ```yaml Resolved configuration theme={null}
> inheritance: true
> language: "de-DE" # scalar: the repository wins
> reviews:
>   profile: assertive # scalar: the repository wins
>   high_level_summary: true # only central sets it
>   auto_review: # object: merged key by key
>     enabled: true # from central
>     drafts: false # the repository wins
>     labels: # list of values: repository entries first, then new central entries
>       - "!do-not-review"
>       - "!wip"
>   path_instructions: # list of objects: matched by path
>     - path: "src/**"
>       instructions: "Use strict TypeScript settings." # replaces the central src/** entry
>     - path: "api/**"
>       instructions: "Validate API contracts."
>     - path: "docs/**"
>       instructions: "Check for grammar and clarity." # from central
> chat:
>   art: false # only central sets it
> ```
>
> Schema defaults fill every key that neither file sets.

## What's next

> [card] [Global overrides](https://docs.coderabbit.ai/configuration/global-overrides.md)
>
> Enforce settings on top of every repository and force inheritance everywhere.

> [card] [Workspace settings](https://docs.coderabbit.ai/configuration/workspace.md)
>
> Share a baseline across organizations and fill unset values.

> [card] [Apply settings to every repository](https://docs.coderabbit.ai/configuration/guides/all-repositories.md)
>
> Combine central configuration and inheritance for an organization-wide baseline.


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