Skip to main content
| Configuration V3 groups review behavior, output, and automatic-review settings, and moves review instructions and custom checks into Markdown files. A migration changes more than the version number: some fields move, some features have separate settings, and some V2 options are retired.

​
Availability

V3 is a limited preview for explicitly enabled organizations using CodeRabbit Cloud with GitHub Cloud. Adding version: 3, creating .coderabbit/, or enabling early_access does not grant access. Follow this guide only after CodeRabbit confirms that access is enabled for your organization. Otherwise, keep your V2 configuration. This guide covers a repository-root .coderabbit.yaml or .coderabbit.yml. Central configuration, TypeScript configuration, other Git providers, self-hosted CodeRabbit, and executable QA-agent migration are outside this preview procedure. Keep existing QA definitions in their current location.

​
How CodeRabbit selects a version

CodeRabbit first selects the configuration source using the existing priority rules, then reads its version. In a selected YAML file: A schema URL in an editor comment does not select the runtime version. A document that declares V3 but fails V3 validation is not retried as V2. Fix the error or restore the original V2 file. Keep one repository YAML file: .coderabbit.yaml takes precedence over .coderabbit.yml when both exist. A YAML file also takes precedence over .coderabbit.config.ts. The version used for settings in the web UI is managed separately; changing a repository file does not migrate the organization’s saved UI settings.

​
1. Capture the current behavior

Save the original V2 file and identify the other settings that affect the repository: organization defaults, repository UI settings, central configuration, workspace defaults, and global overrides. Include inherited path instructions and checks in this inventory. Use the configuration command on a pull request to inspect the resolved settings and their sources: Shows the resolved CodeRabbit configuration for the repository, with comments that say where each setting comes from.
  • Post in: A pull request comment (the whole comment must be the command)
The resolved output is useful for comparison. It is not a V3 migration file: it can contain effective values supplied by other settings sources and uses the resolved setting names from the review runtime. Record the behavior you intend to preserve, especially automatic review admission, review paths, approval rules, privacy preferences, and custom checks. Review any intentional behavior changes before replacing the active file. There is no public CLI migration command for this preview; coordinate the migration review with your CodeRabbit contact.

​
2. Map settings to their V3 locations

Use the V3 reference for the complete authoring schema. Common changes include: Do not copy the V2 reviews object unchanged beneath version: 3. For example, this V3 document sets an assertive profile, keeps reviews off draft pull requests, and places summaries in the walkthrough:

​
Missing fields and inheritance

Authored settings remain sparse: leaving a field out does not save its schema default as an explicit repository value. CodeRabbit resolves applicable inherited settings and overrides, then fills remaining values with defaults. With inheritance: false, omitted review fields ordinarily use defaults rather than parent configuration. Global overrides and eligible workspace defaults have their own rules. Choose inheritance deliberately. Set inheritance: true when the repository should continue receiving applicable parent settings, following the inheritance rules. Explicit scalar values take precedence over inherited values, even when they equal a default. Lists follow the existing merge rules; an empty list is not a general-purpose way to clear inherited entries. Copying all resolved values into a file pins those values. Future edits to organization defaults will no longer change those explicitly authored values. A migration that freezes today’s effective configuration can therefore preserve today’s behavior while changing how future updates reach the repository.

​
Settings with separate owners

V3 review YAML does not own every account or workflow preference. Before switching, have an authorized administrator confirm these settings in their appropriate account, repository, integration, or workflow controls:
  • Early-access preferences and repository exceptions.
  • Knowledge Base connections, scopes, and privacy settings.
  • Chat integrations.
  • Finishing Touches, post-merge actions, and code-generation instructions.
  • Issue Enrichment and automatic-review exclusions by author or title.
Do not remove these settings from your migration inventory because they are absent from the V3 file. Confirm that their V3 preferences are preserved separately, without changing settings still used by V2 branches. Some transfers require help during the preview; do not invent a replacement YAML key.

​
Retired behavior and changed defaults

V3 disables poems, sequence diagrams, code-review effort estimates, and the walkthrough’s linked-issue assessment. These removed options cannot be restored by copying their V2 keys into V3 or inheriting them from a V2 parent. V3 has no pre_merge_checks YAML section, including the earlier preview path reviews.output.pre_merge_checks. Those authored keys are configuration errors. Built-in title, description, and issue-assessment checks are disabled in V3, even when V2 parent settings enable them. Existing custom checks and directory checks retain their supported behavior. Art and in-progress fortunes default to off in V3; explicitly inherited or authored values can still enable them. Compare the V3 defaults with the current resolved configuration instead of assuming that omission preserves every V2 default. The old chat auto-reply and AI-agent-prompt opt-outs are also removed in V3.

​
3. Move instructions and custom checks

The directory name is .coderabbit/. CodeRabbit detects it automatically where configuration directories are supported; there is no configuration-directory field to add. Directory availability is separate from V3 access, and directories also work with V2. Use .coderabbit/instructions/ for guidance that shapes review feedback. Use .coderabbit/pre-merge-checks/ for explicit pass/fail criteria and a reported check result. Instructions do not produce a separate check result or replace check enforcement. Move each inline path instruction into a Markdown document. For example, .coderabbit/instructions/currency.md:
Move each custom check into .coderabbit/pre-merge-checks/. For example, .coderabbit/pre-merge-checks/currency-tests.md:
For a retired built-in check, decide which policy you still need, write its criteria in a directory check, and test both passing and failing pull requests. There is no automatic conversion of built-in checks to Markdown, and a custom replacement is not guaranteed to behave identically. Directory checks use the existing custom-check plan requirements and limits; replacing a built-in check can require a plan that includes custom checks. Use a stable id, valid YAML front matter, and a nonempty body for enabled documents. Paths are relative to the directory containing .coderabbit/. Nested definitions with the same kind and ID replace the parent’s definition within their scope. See Configuration directory for complete scope and validation rules. Remove migrated inline definitions from the V3 source. Also check inherited definitions: instructions can otherwise apply twice, and an active inline check cannot share a directory check’s display name. Retain copies of the original definitions for rollback and for branches that still use V2. The directory limit is 100 discovered documents and 2 MiB of total UTF-8 source. Instruction bodies allow 20,000 characters; check bodies allow 10,000. Symbolic links and submodules are unsupported. Keep QA definitions where they are; these examples do not migrate executable QA agents.

​
4. Verify a review before completing the switch

Use a trusted test pull request in the enabled repository. Include a code change that matches the instruction and check paths, so the review exercises the policies. Configuration selection still follows the repository’s trust rules; a file on a pull request branch is not automatically the selected source.
  1. Confirm that the configuration command identifies the intended V3 source and revision, then compare the resolved settings with the saved V2 baseline.
  2. Wait for the review to finish. Check that the directory instruction affects the review and that each custom check, including any replacement for a retired built-in, reports its expected result.
  3. Fix a deliberately failing condition in the test pull request and confirm that a new review reports the corrected result.
  4. Resolve configuration errors and unexpected behavior changes before merging the migration.
The configuration command alone does not prove that directory documents were loaded during a review. A successful settings lookup can report directory context as not loaded. Directory documents require a complete snapshot or the review’s available checkout; CodeRabbit does not fetch missing document bodies as a fallback. An unavailable directory is a read failure, not an empty set of policies. If a normal review cannot load it, contact support with the pull request and diagnostic message.

​
Roll back to V2

Restore the original V2 configuration, including its field names and inline instructions and checks. Changing only version: 3 to version: 2, or deleting the version from a V3-shaped file, does not reverse the migration. Revert the directory documents introduced by the migration if their restored inline definitions would duplicate or conflict with them. Directory discovery also works with V2, so restoring the YAML alone does not disable those documents. Preserve any directory files that existed before the migration. Coordinate rollback of any separately changed preferences with their administrator, preserving the settings needed by branches still using V3. Run the configuration command again and verify a completed review against the restored V2 behavior.

​
What’s next

V3 configuration reference

Look up the supported V3 fields and defaults.

Configuration directory

Scope instructions and checks to the right parts of your repository.

Configuration inheritance

Decide which settings should continue flowing from parent sources.