> ## 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. # Configuration directory > Store review instructions and custom pre-merge checks in Markdown files, with rules scoped to each part of your repository. GitHub Cloud (The directory preview supports GitHub Cloud only.) | Cloud Only (This feature is available on CodeRabbit Cloud only. It is not available on self-hosted CodeRabbit deployments.) Preview (Available only in enabled preview repositories. The early\_access setting does not enable this preview.) Use a `.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 setting `early_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. | Directory | Purpose | Result | | - | - | - | | `.coderabbit/instructions/` | Guide the review of matching files. | Review guidance. | | `.coderabbit/pre-merge-checks/` | Define a condition that CodeRabbit checks against the pull request. | A check result, reported to GitHub or in CodeRabbit. | 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: ```text theme={null} . ├── .coderabbit.yaml ├── .coderabbit/ │ ├── instructions/ │ │ └── api-security.md │ └── pre-merge-checks/ │ └── migration-notes.md └── services/ └── api/ └── .coderabbit/ └── instructions/ └── api-security.md ``` For example, create `.coderabbit/instructions/api-security.md`: ```markdown theme={null} --- id: api-security paths: - "services/api/**" exclude: - "services/api/generated/**" --- Check that each API endpoint validates input and checks authorization. Flag database calls that bypass the service's data access layer. ``` Create `.coderabbit/pre-merge-checks/migration-notes.md`: ```markdown theme={null} --- id: migration-notes name: Migration notes paths: - "db/migrations/**" mode: warning --- Pass if the pull request description explains the purpose of each database migration and how to recover if deployment fails. Fail if either is missing. ``` The check runs when the pull request changes a matching path. Because `report` is omitted, it uses the default `platform` value and reports through a GitHub Check Run. See [custom checks](https://docs.coderabbit.ai/pr-reviews/custom-checks.md) 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: | Field | Required | Meaning | | - | - | - | | `id` | Yes | Stable identifier, up to 50 characters. Start with a letter or digit. Use letters, digits, `.`, `_`, or `-`. File names do not set the identity. | | `name` | No | Display name, from 1 to 50 characters. A check uses its `id` as its display name when this is omitted. | | `paths` | No | List of glob patterns relative to the directory that contains `.coderabbit/`. Omit it to match all paths in that scope. An empty list matches no paths. | | `exclude` | No | List of glob patterns to exclude within that scope. Defaults to an empty list. | | `enabled` | No | Defaults to `true`. Set to `false` to disable a document or an inherited definition with the same ID. | Check documents also accept [`mode` and `report`](https://docs.coderabbit.ai/pr-reviews/custom-checks#check-front-matter). 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](https://docs.coderabbit.ai/configuration/path-instructions.md#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/`. For example, `services/api/.coderabbit/instructions/api-security.md` can replace the root instruction for API files: ```markdown theme={null} --- id: api-security paths: - "src/**" --- Check that each handler calls the shared authorization middleware before it reads or changes customer data. ``` CodeRabbit selects this nested definition before it evaluates `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`: ```markdown theme={null} --- id: api-security enabled: false --- ``` These directory rules do not require the YAML `inheritance` setting. [Configuration inheritance](https://docs.coderabbit.ai/configuration/configuration-inheritance.md) controls how settings merge between repository, organization, and other configuration sources. ## Use existing YAML definitions Directory instructions apply alongside inline `reviews.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](https://docs.coderabbit.ai/pr-reviews/custom-checks.md#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. | Limit | Value | | - | - | | Discovered documents across the supported directories | 100 | | Total document source, including front matter | 2 MiB of UTF-8 data | | Instruction body | 20,000 characters | | Check body | 10,000 characters | 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. | Symptom | What to check | | - | - | | No directory instructions or checks appear | Confirm that the repository is enabled for the preview. Check the selected revision, directory name, `.md` extension, and path patterns. | | A parent rule does not apply | Check for a closer definition with the same kind and ID, including one with `enabled: false` or patterns that do not match. | | A configuration error names a document | Fix its YAML front matter, duplicate ID, body, or size. Unknown fields are not ignored. | | A check conflicts with an inline check | Remove or disable the inline check with the same display name. | | Directory context cannot be loaded completely | Treat this as a read failure, not as an empty directory. If it persists, [contact support](https://docs.coderabbit.ai/support) with the pull request link and error message. | 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 > [card] [Path-based review instructions](https://docs.coderabbit.ai/configuration/path-instructions.md) > > Write instructions for specific files and directories. > [card] [Custom checks](https://docs.coderabbit.ai/pr-reviews/custom-checks.md) > > Define pass and fail criteria and choose where results appear. > [card] [Configuration overview](https://docs.coderabbit.ai/guides/configuration-overview.md) > > Choose the settings source for your repository. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.