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

# Instruction and check documents

> Store review instructions and custom pre-merge checks as Markdown files in a .coderabbit/ directory, and scope them to the packages and paths they apply to.

A `.coderabbit/` directory holds Markdown documents with YAML front matter. Each document is either review guidance (an instruction) or a condition CodeRabbit checks against the pull request (a check). You can place a directory at the repository root and inside individual packages or services.

## Availability

`.coderabbit/` documents work on GitHub Cloud with CodeRabbit Cloud. GitHub Enterprise Server, other Git providers and self-hosted CodeRabbit don't read them. CodeRabbit detects the directory automatically: you don't set a flag, and your existing V2 settings keep working.

## What the directory holds

| Folder | Purpose | Produces a check result? |
| - | - | - |
| `.coderabbit/instructions/` | Guidance that shapes review feedback for matching files | No |
| `.coderabbit/pre-merge-checks/` | A condition checked against the pull request, with a reported result | Yes |

The directory supplements your settings. It doesn't replace the configuration file, doesn't choose a different settings source, and doesn't decide whether a review starts. Keep settings such as automatic review in YAML, TypeScript or the web app. See [Compare every place settings can live](https://docs.coderabbit.ai/configuration.md#compare-every-place-settings-can-live).

## Quick start

A root layout with one nested override for a service:

```text theme={null}
.
├── .coderabbit.yaml
├── .coderabbit/
│   ├── instructions/
│   │   └── api-security.md
│   └── pre-merge-checks/
│       └── migration-notes.md
└── services/
    └── api/
        └── .coderabbit/
            └── instructions/
                └── api-security.md
```

**1. Create the folder**

Add `.coderabbit/instructions/` at the repository root.

**2. Add a document**

Create a `.md` file with front matter and a body. See the example below.

**3. Open a pull request**

CodeRabbit reads the directory from the revision that your [configuration branch policy](https://docs.coderabbit.ai/configuration/branch.md) allows.

## Write a document

Each document starts with YAML front matter and continues with the Markdown body that CodeRabbit reads.

```markdown Instruction theme={null}
---
id: api-security
name: API security
paths:
  - "src/api/**"
exclude:
  - "**/*.test.ts"
---

Check that every new endpoint validates its input and requires authentication.
```

```markdown Check theme={null}
---
id: migration-notes
mode: warning
report: platform
paths:
  - "db/migrations/**"
---

Fail when a migration changes a table without a note in the pull request description.
```

| Field | Required | Applies to | Default | Rules |
| - | - | - | - | - |
| `id` | Yes | All | None | Up to 50 characters. Starts with a letter or digit. Letters, digits, `.`, `_` and `-`. The file name doesn't set identity. |
| `name` | No | All | `id` for checks | 1 to 50 characters. |
| `paths` | No | All | All paths in scope | Globs relative to the directory that contains `.coderabbit/`. An empty list matches no paths. |
| `exclude` | No | All | `[]` | Globs. Exclusions beat `paths`. |
| `enabled` | No | All | `true` | `false` disables the document, or an inherited definition with the same ID. |
| `mode` | No | Checks | `warning` | `off`, `warning` or `error`. |
| `report` | No | Checks | `platform` | `platform` posts a GitHub Check Run. If CodeRabbit confirms that the Checks write permission is missing, it shows the result in the Walkthrough with a [permission notice](https://docs.coderabbit.ai/pr-reviews/pre-merge-checks.md#missing-github-checks-permission). `coderabbit` reports in the Walkthrough. |

Unknown fields and duplicate YAML keys are errors. Patterns can't be absolute or contain `..`, and they can match hidden files (names starting with a dot). Patterns choose where a document applies. They don't change which files [CodeRabbit reviews](https://docs.coderabbit.ai/pr-reviews/which-files.md).

## Scope a document to paths

Patterns are relative to the directory that contains `.coderabbit/`.

| Document location | Pattern | Matches |
| - | - | - |
| `.coderabbit/instructions/x.md` | `src/**` | `src/**` in the repository |
| `services/api/.coderabbit/instructions/x.md` | `src/**` | `services/api/src/**` |
| Any location, `paths` omitted | None | Every path in the document's scope |

## Nest documents in packages and services

CodeRabbit resolves documents for each changed path. Documents with different IDs apply together. For the same kind and ID, the closest directory replaces the parent definition, and a nested definition affects only its own directory.

```mermaid theme={null}
flowchart TD
  A[".coderabbit/instructions/api-security.md"] --> B["services/web: parent applies"]
  A --> C["services/api: replaced"]
  D["services/api/.coderabbit/instructions/api-security.md"] --> C
```

> [!WARNING]
>
> CodeRabbit picks the closest definition with the same kind and ID before it evaluates `paths` and `exclude`. A nested definition with narrower `paths` can leave files that neither it nor the parent covers. To add a rule without replacing the parent, use a different ID.

To switch off a parent instruction in a subdirectory, add a nested document with the same ID, `enabled: false` and no `paths`. A duplicate ID within the same kind and scope is an error, even across different file names or subdirectories.

Nested documents add no level to the settings hierarchy and don't need `inheritance: true`. See [Inheritance and merging](https://docs.coderabbit.ai/configuration/inheritance-and-merging.md).

## Use documents with V2 and V3 settings

> [tab] YAML V2
>
> Directory instructions apply together with inline `reviews.path_instructions`. Neither replaces the other. When you move an instruction into a document, remove the inline entry so both don't apply.
>
> ```yaml theme={null}
> reviews:
>   path_instructions:
>     - path: "src/api/**"
>       instructions: "Check that every new endpoint validates its input."
> ```

> [tab] YAML V3
>
> Early Access (This feature is in early access. Enable it by setting `early_access: true` in your `.coderabbit.yaml`, or by toggling Early Access on the web interface.)
>
> V3 is a limited preview. Adding `version: 3` doesn't give your organization access.
>
> V3 YAML has no `reviews.path_instructions` and no `reviews.pre_merge_checks`. Instructions live in `.coderabbit/instructions/`, custom checks in `.coderabbit/pre-merge-checks/`. CodeRabbit turns the built-in docstrings, title, description and issue assessment checks off. Instruction documents give guidance without their own check result.

V3 is a limited preview. Directory documents are available separately from V3 access and work with V2.

## Which revision CodeRabbit reads

The directory revision follows your [configuration branch policy](https://docs.coderabbit.ai/configuration/branch.md). It isn't always the pull request branch.

* **Auto.** The head ref for [trusted](https://docs.coderabbit.ai/configuration/branch.md#who-counts-as-trusted) pull requests. The target ref for fork pull requests and pull requests from authors who aren't trusted.
* **Default branch.** The default branch. With **Allow configuration changes from trusted PRs** on, a trusted same-repository head supplies the directory.

Directory-only changes never switch the revision CodeRabbit reads for your YAML or TypeScript file. Documents must live in the repository under review. CodeRabbit doesn't load them from a [central configuration](https://docs.coderabbit.ai/configuration/central.md) repository.

## Limits

| Limit | Value |
| - | - |
| Discovered documents | 100 |
| Total source, including front matter | 2 MiB (UTF-8) |
| Instruction body | 20,000 characters |
| Check body | 10,000 characters |

Files must be regular `.md` files. CodeRabbit ignores `README.md` in any case. Subdirectories inside `instructions/` and `pre-merge-checks/` are allowed and create no new scopes. Symlinks and submodules aren't supported. Whitespace counts toward the character limits.

An enabled document needs a non-empty body. Disabled documents still need valid front matter and count toward the limits. CodeRabbit validates every discovered document, including those whose paths don't match the pull request.

## Troubleshoot documents

If the revision CodeRabbit reads has no `.coderabbit/` directory, or the directory holds no recognized documents, the review runs normally without a message.

| Symptom | Cause | Fix |
| - | - | - |
| No document applies, and the review shows no warning | The repository isn't on GitHub Cloud, the file isn't a `.md` file under `instructions/` or `pre-merge-checks/`, the file is a `README.md`, the revision read doesn't contain the document, or `paths` doesn't match | Check **Source mode** and **Commit** in the review's **Run configuration**, then the folder, file name and patterns. A fork pull request reads the target branch. |
| A parent document doesn't apply in a subdirectory | A closer document with the same kind and ID replaces it, including one with `enabled: false` or narrower `paths` | Give the nested document a different ID to add a rule instead of replacing one. |
| The review stops, and a CodeRabbit check run on the pull request reports an invalid configuration | A document has missing or invalid front matter, an unknown field, a duplicate ID, an empty body in an enabled document, a body over its limit or an invalid pattern, or a check has the same name as an active inline check | Read the file and reason in the check run, fix the document, and request a new review. One invalid document rejects the whole set. |
| The review summary warns that the configuration directory couldn't be loaded | CodeRabbit couldn't read the directory completely: a read failure or timeout, more than 100 documents or 2 MiB, a symbolic link or submodule, or text that isn't UTF-8 | The review ran without directory documents. It didn't evaluate directory instructions or checks, and automatic approval is withheld. Check the limits. If the warning persists, [contact support](https://docs.coderabbit.ai/support) with the pull request link. |

A read failure isn't an empty directory. CodeRabbit doesn't fetch missing document bodies another way, and directory checks that earlier reviews reported show as failed in a review that couldn't read the directory.

A review with no new reviewable code, for example when path filters exclude every changed file, can finish without loading the directory. A finished review then doesn't prove that CodeRabbit read the directory. When the pull request changes `.coderabbit/`, has results from directory checks, or CodeRabbit can't get the complete list of changed files, it doesn't count such a review as complete without the directory.

`@coderabbitai configuration` doesn't load directory documents, so its reply can't show whether they applied. For the step-by-step diagnosis, see [Write review instructions that work](https://docs.coderabbit.ai/configuration/guides/write-instructions.md).

## What's next

> [card] [Teach CodeRabbit your review rules](https://docs.coderabbit.ai/pr-reviews/review-instructions.md)
>
> Choose between path instructions, code guidelines, documents and custom checks.

> [card] [Configure a monorepo](https://docs.coderabbit.ai/configuration/guides/monorepo.md)
>
> Give each package its own documents, filters and tool configuration.

> [card] [Custom checks](https://docs.coderabbit.ai/pr-reviews/custom-checks.md)
>
> Define pass or fail conditions that CodeRabbit reports on the pull request.


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