Skip to main content
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

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.

Quick start

A root layout with one nested override for a service:
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 allows.

Write a document

Each document starts with YAML front matter and continues with the Markdown body that CodeRabbit reads.
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.

Scope a document to paths

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

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

Use documents with V2 and V3 settings

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.
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. It isn’t always the pull request branch.
  • Auto. The head ref for 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 repository.

Limits

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

What’s next

Teach CodeRabbit your review rules

Choose between path instructions, code guidelines, documents and custom checks.

Configure a monorepo

Give each package its own documents, filters and tool configuration.

Custom checks

Define pass or fail conditions that CodeRabbit reports on the pull request.