Skip to main content
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 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. 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.
Central configuration shares settings. It doesn’t share guideline file content from another repository. That is a separate mechanism under Code guidelines.

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.

Example: a central file and a repository override

.coderabbit.yaml in the coderabbit repository
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.

Name the repository for your platform

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

Share TypeScript fragments

A repository that uses TypeScript configuration can pull a fragment from the coderabbit repository and combine it with its own settings instead of replacing central configuration.
.coderabbit.config.ts
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 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.
.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.
  • URL form. HTTPS only. CodeRabbit fetches it without authentication, with a five-second timeout and no redirects.
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

Inheritance and merging

Merge central settings with a repository’s own.

Apply to every repository

Choose between central, web, and workspace defaults.

TypeScript configuration

Build shared fragments in code.