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

# TypeScript configuration reference

> Every field of the context object that a .coderabbit.config.ts function receives, what each status value means, and every function and type the @coderabbitai/config SDK exports.

This page lists the context object that CodeRabbit passes to a configuration function, and the functions and types of the `@coderabbitai/config` SDK. To write a configuration, start with [TypeScript configuration](https://docs.coderabbit.ai/configuration/typescript.md).

## Context object

When the default export is a function, CodeRabbit calls it with a context object that describes the review. CodeRabbit computes the object on the server and injects it into the sandbox. It holds metadata only: no tokens, credentials or secrets.

CodeRabbit looks up the context only while it evaluates a TypeScript configuration. The lookups use the permissions CodeRabbit already has to read repository metadata. Your configuration code never receives credentials and can't make network requests. A field that CodeRabbit can't resolve degrades, as described in each table, instead of failing the configuration.

### Invocation and platform

| Field | Type | Meaning |
| - | - | - |
| `ctx.invocation.source` | `"cli" \| "review"` | `"cli"` for a local `coderabbit review`. `"review"` for every other start, including pull request reviews and IDE reviews. |
| `ctx.platform` | `string` | The Git platform: `GitHub` (also for GitHub Enterprise Server), `GitLab`, `Azure DevOps`, `Bitbucket Cloud` or `Bitbucket Data Center`. In CLI and IDE reviews, the surface, such as `cli`, `vscode`, `cursor`, `windsurf` or `jetbrains`. |

### Repository

| Field | Type | Meaning |
| - | - | - |
| `ctx.repo.owner` | `string` | Repository owner or namespace |
| `ctx.repo.name` | `string` | Repository name |
| `ctx.repo.fullName` | `string` | Full name, for example `acme/api`. On GitLab, the path with its namespace. |
| `ctx.repo.language` | `string \| null` | The repository's primary programming language as the platform reports it, for example `TypeScript`. It isn't the top-level `language` setting, which sets the natural language of reviews. `null` when the platform reports none. |
| `ctx.repo.isPrivate` | `boolean` | `true` for a private repository |
| `ctx.repo.isSelfHosted` | `boolean` | `true` on an instance you host, such as GitHub Enterprise Server, self-managed GitLab or Bitbucket Data Center |
| `ctx.repo.defaultBranch` | `string` | Name of the default branch. An empty string when CodeRabbit couldn't read it, so check for an empty value before you rely on it. |
| `ctx.repo.topics` | `CodeRabbitRepositoryTopicsContext` | `status`, and `names`: the repository's topics, sorted. GitHub only. |
| `ctx.repo.customProperties` | `CodeRabbitRepositoryCustomPropertiesContext` | `status`, and `values`: the repository's custom properties, keyed by property name. Each value is a string, a list of strings, or `null`. GitHub only. |
| `ctx.org` | `{ name: string } \| null` | The owning organization, or `null` when the platform has none or CodeRabbit couldn't resolve it |

### Pull request

`ctx.pr` is `null` when the event has no pull request, or when CodeRabbit couldn't read it. CodeRabbit resolves it for every event that starts a review, not only for a new pull request: comment commands such as `@coderabbitai review`, label events and repeated reviews included.

| Field | Type | Meaning |
| - | - | - |
| `ctx.pr.number` | `number` | Pull request number |
| `ctx.pr.title` | `string` | Pull request title |
| `ctx.pr.baseBranch` | `string` | The branch the pull request merges into |
| `ctx.pr.headBranch` | `string` | The branch the pull request comes from |
| `ctx.pr.author` | `string` | The author's username |
| `ctx.pr.authorAssociation` | `string \| null` | On GitHub, the author's association with the repository: `OWNER`, `MEMBER`, `COLLABORATOR`, `CONTRIBUTOR`, `FIRST_TIME_CONTRIBUTOR`, `FIRST_TIMER`, `MANNEQUIN` or `NONE`. `null` on other platforms. |
| `ctx.pr.authorGroups` | `CodeRabbitAuthorGroupsContext` | `status`, and `groups`: the author's teams or groups. See [Author groups](#author-groups). |
| `ctx.pr.labels` | `readonly string[]` | Label names on the pull request. Empty when CodeRabbit couldn't read the labels. |
| `ctx.pr.isDraft` | `boolean` | `true` for a draft pull request |
| `ctx.pr.changedFiles` | `CodeRabbitChangedFilesContext` | `status`, and `paths`: the changed files. See [Changed files](#changed-files). |

### Author groups

Each entry of `ctx.pr.authorGroups.groups` has three fields. The list is sorted by `fullPath`.

| Field | Type | Meaning |
| - | - | - |
| `id` | `string` | The platform's stable ID of the team or group |
| `slug` | `string` | Short name, for example `platform-usa` |
| `fullPath` | `string` | Path including the organization or parent groups, for example `acme/platform-usa` |

What the list holds depends on the platform:

* **GitHub and GitHub Enterprise Server:** the teams in the repository's organization that the author belongs to and CodeRabbit can see.
* **GitLab:** the author's direct group memberships under the repository's top-level group. Inherited and shared memberships aren't included.
* **Other platforms, CLI and IDE reviews:** `status` is `unsupported`.

### Changed files

`ctx.pr.changedFiles.paths` lists every file the pull request changes, as paths relative to the repository root. For a renamed file, it holds both the old and the new path, so a rule can't miss a file that moves into or out of a protected directory. `paths` is empty unless `status` is `resolved`. This field never reports `stale`.

### Status values

`authorGroups`, `changedFiles`, `topics` and `customProperties` each carry a `status`.

| Status | Meaning |
| - | - |
| `resolved` | CodeRabbit got a complete answer. An empty list is authoritative: the author is in no visible groups, or the repository has no topics. |
| `unavailable` | The platform supports the lookup, but it didn't complete: a timeout, a missing permission, a platform error, a safety limit, or a GitHub Enterprise Server version without the API. The list is empty, and that means "unknown", not "none". |
| `unsupported` | The platform or the review surface has no such lookup. The list is empty. |
| `stale` | Reserved for cached results. CodeRabbit doesn't return it. |

Use the values for a decision only when `status` is `resolved`, and decide what an unknown result should mean for your rule.

## API reference

The SDK is optional and only adds types; see [Install the SDK](https://docs.coderabbit.ai/configuration/typescript.md#install-the-sdk). During evaluation, CodeRabbit supplies its own `defineConfig`, `mergeConfig` and `includeRemote`, which behave the same.

### Functions

| Function | What it does |
| - | - |
| `defineConfig(config)` | Returns its argument unchanged, typed as a configuration. Accepts a configuration object, or a function that receives the context and returns a configuration. The function can be `async`. |
| `mergeConfig(...configs)` | Deep-merges configurations from left to right and returns the result. Objects merge recursively, arrays concatenate, the later scalar wins, and an omitted key never overwrites a value. |
| `includeRemote({ repo?, path, ref? })` | Includes a configuration file from another repository and returns its configuration. CodeRabbit resolves it while it bundles the file, so the argument must be an inline object literal with string-literal values. `repo` uses the platform's own format, such as `owner/repository` on GitHub or `group/subgroup/project` on GitLab, and defaults to the `coderabbit` repository. `ref` takes a branch, tag or commit and defaults to the default branch. |

### Types

| Type | What it describes |
| - | - |
| `CodeRabbitConfig` | The configuration object: the `.coderabbit.yaml` schema as a TypeScript type, with every key optional |
| `CodeRabbitConfigFactory` | A function that receives the context and returns a `CodeRabbitConfig` or a promise of one |
| `CodeRabbitContext` | The context object, with `invocation` and the four lookup fields optional. See [Context types](#context-types). |
| `ResolvedCodeRabbitContext` | The context object with `invocation` required |
| `CodeRabbitInvocationContext` | `ctx.invocation`: `{ source }` |
| `CodeRabbitInvocationSource` | `"cli" \| "review"` |
| `CodeRabbitRepositoryContext` | `ctx.repo` |
| `CodeRabbitPullRequestContext` | `ctx.pr` when a pull request exists |
| `CodeRabbitAuthorGroupsContext` | `ctx.pr.authorGroups`: `{ status, groups }` |
| `CodeRabbitAuthorGroup` | One entry of `groups`: `{ id, slug, fullPath }` |
| `CodeRabbitAuthorGroupsStatus` | The `status` of `authorGroups`, the same union as `CodeRabbitContextResolutionStatus` |
| `CodeRabbitContextResolutionStatus` | `"resolved" \| "stale" \| "unavailable" \| "unsupported"` |
| `CodeRabbitChangedFilesContext` | `ctx.pr.changedFiles`: `{ status, paths }` |
| `CodeRabbitChangedFilesStatus` | `"resolved" \| "unavailable" \| "unsupported"` |
| `CodeRabbitRepositoryTopicsContext` | `ctx.repo.topics`: `{ status, names }` |
| `CodeRabbitRepositoryCustomPropertiesContext` | `ctx.repo.customProperties`: `{ status, values }` |
| `CodeRabbitRepositoryCustomPropertyValue` | One custom property value: `string \| readonly string[] \| null` |
| `RemoteInclude` | The argument of `includeRemote`: `{ repo?, path, ref? }` |
| `CodeRabbitConfigV3`, `CodeRabbitConfigV3Fragment`, `CodeRabbitConfigV3Factory` | The same shapes for a configuration with `version: 3`. V3 is a limited preview. Adding `version: 3` doesn't give your organization access. |

### Context types

The function you pass to `defineConfig` receives the full context, where `invocation`, `repo.topics` and `repo.customProperties` are always present, and `pr.authorGroups` and `pr.changedFiles` are present whenever `ctx.pr` isn't `null`. The exported types are looser, so code that builds a context object by hand keeps compiling:

* `CodeRabbitContext` keeps all five fields optional.
* `ResolvedCodeRabbitContext` requires `invocation`. The four lookup fields stay optional.

When you type a helper's parameter with one of these types, as in the [hotfix example](https://docs.coderabbit.ai/configuration/typescript.md#review-hotfixes-more-strictly), read the optional fields with `?.`, or pass the helper only the values it needs.

## What's next

> [card] [TypeScript configuration](https://docs.coderabbit.ai/configuration/typescript.md)
>
> Write a configuration that adapts to each pull request.

> [card] [Validate and test a change](https://docs.coderabbit.ai/configuration/guides/validate-and-test.md)
>
> Type-check the file in CI and test it before you merge.

> [card] [Configuration reference](https://docs.coderabbit.ai/reference/configuration.md)
>
> Look up every setting the configuration object accepts.


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