.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.
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 ofdefineConfig, 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.
Write a configuration
The default export is a configuration object or a function that returns one, and the function can beasync.
For type checking, wrap it in defineConfig. It returns its argument unchanged, so evaluation works without it.
- TypeScript
- Equivalent YAML
.coderabbit.config.ts
.coderabbit.yaml. See the configuration reference for every setting.
Adapt configuration to the pull request
Pass a function todefineConfig 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
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
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,.yamland.ymlin 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 omitrepo, it reads thecoderabbitrepository.refpins 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 andref. See Read a fragment from another repository for the access rules.- Build-time only. The argument of
includeRemotemust 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
Setrepo 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,repois the fullgroup/subgroup/projectpath, 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
coderabbitrepository skip the same-owner and pull request branch checks.
Layer settings by condition
Passcondition ? 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
AnincludeRemote 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
mergeConfig: ctx.pr?.labels.includes("hotfix") ? includeRemote({ path: "hotfix.ts" }) : {}.
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
The file is ignored
The file is ignored
A
.coderabbit.yaml or .coderabbit.yml exists. Delete it and confirm with @coderabbitai configuration.A function passed to defineConfig fails type checking
A function passed to defineConfig fails type checking
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.Unsupported import
Unsupported import
Only the SDK, relative includes and
includeRemote are allowed. npm packages and Node built-ins fail at bundle time.includeRemote needs a literal argument
includeRemote needs a literal argument
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.An include can't be resolved
An include can't be resolved
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 timed out
Evaluation timed out
Evaluation has a 10-second limit. Remove heavy computation.
The file must resolve to an object
The file must resolve to an object
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.