.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. 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
- YAML V2
- YAML V3
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.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.
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.