.coderabbit/ directory to keep review instructions and custom Pre-Merge Checks in Markdown files. Each file contains YAML front matter followed by the instructions for CodeRabbit. You can place directories at the repository root and inside individual packages or services.
Availability
Configuration directories are not generally available. This guide applies only to repositories enabled for the preview on GitHub Cloud with CodeRabbit Cloud. Creating a directory or settingearly_access: true does not enable this preview. GitHub Enterprise Server, other Git platforms, and self-hosted CodeRabbit are not supported by this preview.
For an enabled repository, CodeRabbit detects .coderabbit/ automatically. You do not need a directory-enable field or a migration to configuration schema V3. Existing V2 settings continue to work.
Keep settings and instructions separate
Keep settings that control whether a review starts, such as automatic review settings, in your existing YAML, TypeScript, or web configuration. Directory documents provide context and checks during a review. They do not replace your configuration file or change which settings source takes priority.
Executable QA-agent definitions belong to a separate flow. They are not part of automatic V2 directory discovery described here.
Quick start
Keep your existing configuration and add Markdown files:.coderabbit/instructions/api-security.md:
.coderabbit/pre-merge-checks/migration-notes.md:
report is omitted, it uses the default platform value and reports through a GitHub Check Run. See custom checks for reporting options and check-specific fields.
Front matter
Start each document with YAML between two--- lines. Put the natural language instructions in the Markdown body below it. These fields apply to both instruction and check documents:
Check documents also accept
mode and report. Instruction documents do not accept those fields. Unknown fields and duplicate YAML keys are errors.
Use relative paths. Absolute paths and .. path segments are not allowed. Exclusions take precedence over matching paths patterns. Patterns can match files whose names start with .. These patterns select where a document applies; they do not change the repository’s review path filters.
Nested directories
A document applies within the directory that contains.coderabbit/. At the repository root, its scope is the whole repository. In services/api/.coderabbit/, its scope is services/api/, and a pattern such as src/** means services/api/src/**.
CodeRabbit resolves definitions for each changed path:
- Definitions with different IDs apply together.
- For the same document kind and ID, the closest directory replaces the parent definition.
- A nested definition affects only its own directory and the files within it. It does not change sibling packages.
- A duplicate ID in the same kind and scope is an error, even if the files have different names or are in different folders within
instructions/.
services/api/.coderabbit/instructions/api-security.md can replace the root instruction for API files:
paths and exclude. For services/api/README.md, the nested definition does not match src/**, so neither this definition nor the root definition with the same ID applies. Use a different ID when you want to add a rule without replacing the parent.
To disable that instruction throughout services/api/, use the same ID with enabled: false and omit paths:
inheritance setting. Configuration inheritance controls how settings merge between repository, organization, and other configuration sources.
Use existing YAML definitions
Directory instructions apply alongside inlinereviews.path_instructions. They do not remove or replace inline entries. When you move an instruction into a Markdown file, remove its old inline entry if you no longer want both.
Directory checks and inline checks share the existing custom-check plan limits. A directory check cannot use the display name of an active inline check. When you move a check, remove the inline definition or set its mode to off. See move a check from YAML or the web UI.
Which revision is used
CodeRabbit uses the repository revision permitted by its configuration source policy. Do not assume it always reads the pull request branch. When that policy permits trusted pull request configuration changes, directory edits can be evaluated from the trusted pull request revision. A directory-only change does not switch the YAML or TypeScript configuration source. Adding these files does not make changes from a fork or an unverified author trusted. Keep directory documents in the repository under review. The directory preview does not load documents from a central or remote configuration repository.Limits and troubleshooting
Use regular files with a lowercase.md extension. CodeRabbit ignores README.md, regardless of the case of that file name. You can organize documents in folders within instructions/ and pre-merge-checks/; those folders do not create new scopes. Symbolic links and submodules are not supported.
An enabled document needs a nonempty body. Disabled documents still need valid front matter and count toward the limits. Body limits include whitespace. CodeRabbit validates the complete discovered set, including documents whose paths do not match the pull request.
If CodeRabbit confirms that the directory is absent or contains no recognized documents, normal review behavior continues.
A request with no new reviewable code can finish without loading optional directory documents when no directory checks are known and CodeRabbit has either a completed review of the same commit or a complete pull request comparison with no directory changes. This does not prove that the directory was inspected. Known checks, directory changes, or incomplete evidence still require resolution.
What’s next
Path-based review instructions
Write instructions for specific files and directories.
Custom checks
Define pass and fail criteria and choose where results appear.
Configuration overview
Choose the settings source for your repository.