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

# Central configuration

> Share one configuration across repositories with a coderabbit repository, a `remote_config` redirect, or TypeScript fragments.

Central configuration gives every repository without its own configuration file a shared set of defaults. You keep the file in one repository named `coderabbit`, and repositories override it by adding their own file. This page also covers two other ways to share configuration: `remote_config` and TypeScript fragments.

## How central configuration works

A `.coderabbit.yaml` or `.coderabbit.config.ts` in the `coderabbit` repository applies to every repository that has no configuration file of its own. Its layer is **Central YAML**. When a repository adds its own file, CodeRabbit uses that file instead, unless [inheritance](https://docs.coderabbit.ai/configuration/inheritance-and-merging.md) merges the two. The central file must use schema V2. CodeRabbit ignores a central file with `version: 3` and shows a warning. If a repository's file turns on inheritance, the review fails instead.

```mermaid theme={null}
flowchart TD
  C[coderabbit repository: .coderabbit.yaml] --> A[Repository without a file]
  C --> B[Another repository without a file]
  D[Repository with its own file] -.->|replaces central| C
```

Central configuration outranks **Repository settings** saved in the web interface. CodeRabbit reads the web interface settings only when no valid central file exists, or when the central file turns on inheritance. If the central file is invalid, CodeRabbit ignores it and adds a warning to the summary.

> [!NOTE]
>
> Central configuration shares settings. It doesn't share guideline file content from another repository. That is a separate mechanism under [Code guidelines](https://docs.coderabbit.ai/knowledge-base/code-guidelines.md).

## Set up a central repository

**1. Create the repository**

Create a repository named exactly `coderabbit`. See the table below for where it lives on your platform.

**2. Add the file**

Add `.coderabbit.yaml` or `.coderabbit.config.ts` at the root of the default branch. If both a YAML file and a TypeScript file exist, the YAML file is used.

**3. Install CodeRabbit on it**

Install CodeRabbit on the `coderabbit` repository itself. CodeRabbit can't read the file otherwise.

**4. Check the result**

Open a pull request in a repository that has no file of its own and comment `@coderabbitai configuration`. The source line names the file from the `coderabbit` repository. See [Check which configuration a review used](https://docs.coderabbit.ai/configuration/guides/check-effective-configuration.md).

## Example: a central file and a repository override

> [tab] Central file
>
> ```yaml .coderabbit.yaml in the coderabbit repository theme={null}
> reviews:
>   profile: chill
>   high_level_summary: true
>   poem: false
>   review_status: true
>   auto_review:
>     enabled: true
>     drafts: true
> chat:
>   art: false
> ```

> [tab] Repository override
>
> ```yaml .coderabbit.yaml theme={null}
> reviews:
>   profile: assertive
>   auto_review:
>     drafts: false
> ```

Repositories without a file of their own use the central file. The repository with the override uses only its own file: the `assertive` profile, no draft reviews, and defaults for every other key. For example, unless a global override sets it, `chat.art` is back to its default, `true`, although the central file turns it off. To keep the central values a repository doesn't set, add `inheritance: true` to the repository file. See [Inheritance and merging](https://docs.coderabbit.ai/configuration/inheritance-and-merging.md).

## Name the repository for your platform

| Platform | Central repository | Notes |
| - | - | - |
| GitHub and GitHub Enterprise Server | `{owner}/coderabbit` | Default branch |
| GitLab | `{group}/coderabbit`, or `{group}/{subgroup}/coderabbit` | Closest repository with a config file wins. See below. |
| Azure DevOps | `coderabbit` in the same project | One repository per project. No sharing across projects. |
| Bitbucket Cloud | `coderabbit` in the workspace | Default branch |
| Bitbucket Data Center | `coderabbit` in the project | Default branch, falling back to `main` |

## Use central configuration in GitLab groups

For each project, CodeRabbit looks for a `coderabbit` project from the innermost namespace outward. It uses the first one that contains a configuration file. A closer `coderabbit` project without a file is skipped.

```mermaid theme={null}
flowchart TD
  P[company/team-a/subteam/project1] --> A[company/team-a/subteam/coderabbit]
  A -->|no config file| B[company/team-a/coderabbit]
  B -->|no config file| C[company/coderabbit]
```

For `company/team-a/subteam/project1`, CodeRabbit tries the three `coderabbit` projects in this order and stops at the first one with a file. CodeRabbit never merges two central files. Install CodeRabbit on the top-level group so it can read the `coderabbit` project at every level.

> [!WARNING]
>
> When a team adds a `coderabbit` project with a configuration file to its subgroup, every project below that subgroup stops getting the top-level group's central file. To enforce a baseline that a subgroup can't replace, use [global overrides](https://docs.coderabbit.ai/configuration/global-overrides.md).

## Share TypeScript fragments

A repository that uses [TypeScript configuration](https://docs.coderabbit.ai/configuration/typescript.md) can pull a fragment from the `coderabbit` repository and combine it with its own settings instead of replacing central configuration.

```ts .coderabbit.config.ts theme={null}
import { defineConfig, includeRemote, mergeConfig } from "@coderabbitai/config"

export default defineConfig(
  mergeConfig(includeRemote({ path: "base.ts" }), { reviews: { profile: "assertive" } }),
)
```

`includeRemote` reads the `coderabbit` repository when you omit `repo`. The repository can be private, and fragments can be `.ts` or `.yaml`. A fragment from another repository follows the [same access rules](#who-can-read-a-shared-repository) as `remote_config`.

## Reference a shared file with `remote_config`

`remote_config` redirects a repository to a configuration file in another repository, or at a public URL. Use it when one team's repositories share a file but you don't want a central repository for the whole organization.

> [tab] GitHub
>
> ```yaml .coderabbit.yaml theme={null}
> remote_config:
>   repository: "shared-configs"
>   ref: "main"
>   path: ".shared-coderabbit.yaml"
> ```

> [tab] GitLab
>
> ```yaml .coderabbit.yaml theme={null}
> remote_config:
>   repository: "your_org_name/shared_configs"
>   path: ".shared-coderabbit.yaml"
> ```

> [tab] URL
>
> ```yaml .coderabbit.yaml theme={null}
> remote_config:
>   url: "https://example.com/.coderabbit.yaml"
> ```

How it behaves:

* **Only key.** The file must contain nothing but `remote_config`. With any other key, CodeRabbit doesn't follow the redirect and reads the file as ordinary configuration.
* **Replace, not merge.** The fetched file replaces your file entirely. It becomes the repository-file layer and can use `inheritance`. It can't contain its own `remote_config`.
* **YAML in the repository only.** Central YAML and TypeScript configuration don't support `remote_config`. In TypeScript, use `includeRemote`.
* **Repository form.** `ref` defaults to `main`. A bare repository name resolves under the reviewed repository's owner. See [Who can read a shared repository](#who-can-read-a-shared-repository).
* **URL form.** HTTPS only. CodeRabbit fetches it without authentication, with a five-second timeout and no redirects.

> [!WARNING]
>
> A `url` must be publicly reachable, so anyone with the link can read your configuration. Prefer the repository form.

### Who can read a shared repository

These rules apply to both `remote_config` and `includeRemote`. The shared repository must have the same owner as the reviewed repository, except on GitLab, where any namespace the CodeRabbit connection can read works. The CodeRabbit installation must be able to read it.

For configuration read from a pull request branch, the pull request author and the person who started the review must both be able to read the shared repository. If CodeRabbit can't confirm that, the configuration fails, and CodeRabbit doesn't fall back to defaults. This check doesn't apply to the reviewed repository or the `coderabbit` repository.

## What's next

> [card] [Inheritance and merging](https://docs.coderabbit.ai/configuration/inheritance-and-merging.md)
>
> Merge central settings with a repository's own.

> [card] [Apply to every repository](https://docs.coderabbit.ai/configuration/guides/all-repositories.md)
>
> Choose between central, web, and workspace defaults.

> [card] [TypeScript configuration](https://docs.coderabbit.ai/configuration/typescript.md)
>
> Build shared fragments in code.


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