Skip to main content
.coderabbit.config.ts lets you author configuration as code. You get autocomplete and type checking, shared fragments, and settings that change with the pull request or the way a review starts. For example, you can use a stricter profile for hotfixes and a different one for local CLI reviews. Start with .coderabbit.yaml, which is simpler to write and review. Switch to TypeScript when static YAML no longer fits, for example when you generate many path instructions from a list, change settings by the pull request’s base branch or changed files, or combine shared fragments with settings of your own.

When CodeRabbit uses the TypeScript file

A committed .coderabbit.yaml or .coderabbit.yml always wins. If either exists, CodeRabbit ignores the TypeScript file. Exactly one file in a repository is used, and the files never merge.
Delete the YAML file to activate .coderabbit.config.ts. Then confirm with @coderabbitai configuration.
The same rule applies in the central configuration repository. A TypeScript file takes the same layer as the YAML file it replaces, so it takes part in inheritance and global overrides like any YAML file.

Install the SDK

The SDK is optional. CodeRabbit evaluates the file on the server with its own implementations of defineConfig, mergeConfig and includeRemote, so the file behaves the same with or without the package. Installing it adds types, editor autocomplete, and type checking in CI. Stable releases go to the default latest tag, so install the package without a tag.
The TypeScript configuration reference lists every function and type the SDK exports.

Write a configuration

The default export is a configuration object or a function that returns one, and the function can be async. For type checking, wrap it in defineConfig. It returns its argument unchanged, so evaluation works without it.
.coderabbit.config.ts
CodeRabbit validates the result against the same schema as .coderabbit.yaml. See the configuration reference for every setting.

Adapt configuration to the pull request

Pass a function to defineConfig to receive a context object that describes the platform, repository and pull request. Annotate the function’s return type with CodeRabbitConfig. Without the annotation, type checking can reject a valid value that the function returns, such as a profile name.
.coderabbit.config.ts
ctx.pr is null for events with no pull request, so guard with ctx.pr?.. A field that can’t be resolved degrades instead of failing the configuration. Four fields come from lookups on the platform: ctx.pr.authorGroups, ctx.pr.changedFiles, ctx.repo.topics and ctx.repo.customProperties. Each carries a status. Rely on the values only when status is "resolved", because an empty list with any other status means “unknown”, not “none”. The TypeScript configuration reference gives the type and meaning of every field and status.

Review hotfixes more strictly

Detect a hotfix from the title, the branch name or a label.
.coderabbit.config.ts

Choose settings by the author’s team

On GitHub and GitLab, ctx.pr.authorGroups lists the author’s teams or groups.
.coderabbit.config.ts
On GitHub, the list holds the author’s teams in the repository’s organization that CodeRabbit can see. On GitLab, it holds the author’s direct group memberships under the repository’s top-level group. Inherited and shared memberships aren’t included.

Use repository topics and custom properties

On GitHub, select settings by repository topics and custom properties instead of keeping a separate file per repository.
.coderabbit.config.ts
topics.names is a sorted list of topic names. customProperties.values is keyed by property name, and each value is a string, a list of strings, or null.

Use a different profile for CLI reviews

ctx.invocation.source tells a local CodeRabbit CLI review apart from every other review. Use it instead of ctx.platform when a setting depends on whether the CLI started the review.
.coderabbit.config.ts
To choose settings by the files a pull request changes, see Vary settings by changed paths.

Generate settings in code

Build repetitive settings from data instead of writing each entry by hand.
.coderabbit.config.ts

Compose configuration from fragments

Split shared settings into fragments and combine them.
.coderabbit.config.ts
  • Local files. Use relative imports, such as import security from "./coderabbit/security". A path resolves against the importing file, at the commit under review. YAML imports (.yaml, .yml) give you the parsed object. Imports can’t leave the repository root.
  • Imports without an extension. CodeRabbit tries .ts, .mts, .cts, .js, .mjs, .cjs, .yaml and .yml in that order, then the same extensions under <path>/index. Each try counts toward the file fetch limit.
  • includeRemote. Pulls a fragment from another repository. When you omit repo, it reads the coderabbit repository. ref pins a branch, tag or commit; without it, the default branch applies and edits propagate. A relative import inside a remote fragment resolves in that fragment’s repository and ref. See Read a fragment from another repository for the access rules.
  • Build-time only. The argument of includeRemote must be an inline object literal with string-literal values. CodeRabbit resolves every call while it bundles the file, before any of your code runs.
  • mergeConfig. Deep-merges fragments from left to right. An omitted key never overwrites a value, so an empty object {} adds nothing.
Because mergeConfig concatenates arrays, two path_instructions entries for the same glob both stay in the result. See Inheritance and merging for the full rules.

Read a fragment from another repository

Set repo to read a fragment from a repository other than coderabbit, and ref to pin a branch, tag or commit.
.coderabbit.config.ts
includeRemote follows the same access rules as remote_config:
  • Same owner. The repository must have the same owner as the reviewed repository. A bare name, such as coderabbit-shared, resolves under that owner. On GitLab, repo is the full group/subgroup/project path, and any namespace the CodeRabbit connection can read works.
  • Installation access. The CodeRabbit installation must be able to read the repository.
  • Pull request branches. When the configuration comes from a pull request branch, the pull request author and the person who started the review must both be able to read the repository.
  • Fail closed. If access is denied or can’t be confirmed, the configuration fails instead of skipping the fragment.
  • Exempt repositories. The reviewed repository and the coderabbit repository skip the same-owner and pull request branch checks.

Layer settings by condition

Pass condition ? fragment : {} to mergeConfig to add settings only when the condition holds. This example adds stricter settings for pull requests into main or a release branch.
.coderabbit.config.ts

Choose a remote fragment by condition

An includeRemote call can sit anywhere in an expression, including either branch of a condition. To replace the whole configuration, choose between two calls:
.coderabbit.config.ts
To layer the fragment onto shared defaults instead, put the condition inside mergeConfig: ctx.pr?.labels.includes("hotfix") ? includeRemote({ path: "hotfix.ts" }) : {}.
CodeRabbit fetches every includeRemote file while it bundles the configuration, including the file in a branch that the condition doesn’t take. If that file is missing or unreadable, the whole configuration fails. Every fetch also counts toward the file fetch limit.

How CodeRabbit evaluates the file

Discovery finds the file in the repository under review. Bundling fetches the entry file and every include. Evaluation runs in a sandbox with no network and no environment secrets. Validation checks the output against the YAML schema. Resolution then applies inheritance, web interface settings and global overrides.

Availability

TypeScript configuration has no plan requirement. CodeRabbit reads .coderabbit.config.ts on every supported Git platform, in CLI reviews, and on self-hosted CodeRabbit. The platform decides which context lookups resolve: On GitHub Enterprise Server, a version without the topics or custom properties API reports unavailable.

Troubleshoot TypeScript configuration

A .coderabbit.yaml or .coderabbit.yml exists. Delete it and confirm with @coderabbitai configuration.
Annotate the return type, as in defineConfig((ctx): CodeRabbitConfig => ({ ... })), or Promise<CodeRabbitConfig> for an async function. Without the annotation, TypeScript can widen a value such as "chill" to string and reject it. A function that returns the result of mergeConfig needs no annotation.
Only the SDK, relative includes and includeRemote are allowed. npm packages and Node built-ins fail at bundle time.
The argument can’t be computed. Write each call with a literal path, and literal repo and ref when you set them. To choose between files, use a condition that selects between two calls.
Check the path, repository and pinned ref, including includes in a branch your condition doesn’t take. For configuration on a pull request branch, the author and the person who started the review must both be able to read the repository.
Evaluation has a 10-second limit. Remove heavy computation.
Add a default export that is an object or a function that returns one.

What’s next

TypeScript configuration reference

Look up every context field, status value and SDK export.

Central configuration

Share fragments from the coderabbit repository.

Validate and test a change

Test a configuration change before you merge it.