.coderabbit/, and manages some settings outside the file. A migration changes more than the version number.
Before you start
- The procedure covers the
.coderabbit.yamlor.coderabbit.ymlfile at the repository root. Central configuration, TypeScript configuration, other Git platforms and self-hosted CodeRabbit are outside the preview. - There is no CLI command that migrates V2 to V3. A CodeRabbit contact coordinates the review of your migration.
- The web interface settings of your organization are managed separately. Changing the file doesnât migrate them.
- Organizations enrolled in V3 review settings on CodeRabbit Cloud use the V3 web interface with every supported Git platform. That doesnât enable V3 repository files outside GitHub Cloud: a V2 file keeps its V2 behavior.
Record your current configuration
1
Save the V2 file
Keep a copy of the original file. You need it to roll back.
2
Record the resolved configuration
Comment
@coderabbitai configuration on a pull request and save the output. It lists each setting with its source: organization defaults, repository settings, central configuration, workspace settings and global overrides.Map V2 keys to V3
Donât copy the V2reviews object under version: 3. Use the key names from the V3 reference. V3 treats unknown, misspelled and moved keys as errors at every level of nesting, and points to the new location of a moved key. For a complete V3 file next to its V2 equivalent, see Use V3 and directory documents.
Keys that move
Keys that become Markdown documents
See Move instructions and checks into documents.
Keys without a V3 key
Keys from an earlier V3 preview
If you wrote a V3 file during an earlier preview, move these keys to their V3 location. They arenât aliases.
Editors and CI jobs that validate against the published V3 schema report every key in this table as an error.
Progress reporting
reviews.behavior.status.progress_updates is one switch for review progress reporting. CodeRabbit reports through a check run when itâs supported and authorized, and through a commit status otherwise. When the check run succeeds, CodeRabbit doesnât also post the commit status.
A V3 layer that sets progress_updates: false and has no legacy_commit_status turns off both formats, even when a parent layer turns legacy_commit_status on. Global overrides still apply. To keep reporting on:
- .coderabbit.yaml
- Web UI
.coderabbit.yaml
CodeRabbit check. With reporting off, the pull request waits for a check that never arrives. Review comments and directory check results donât depend on this switch.
If your V2 configuration posted only a commit status, V3 can post a check run instead on GitHub, when itâs supported and authorized and your organization has check run reporting. After the first review, confirm that your branch rules accept the checkâs name and app. See Require the check before merging.
An existing legacy_commit_status value still counts. CodeRabbit resolves both keys through inheritance and keeps reporting on when either resolved value is true. Before you remove legacy_commit_status to satisfy schema validation, set progress_updates to the behavior you want and check what the file inherits. When a layer leaves out both keys, parent layers supply them.
V2 keeps reviews.review_progress and reviews.commit_status as separate keys. These rules donât change a V2 file.
Move instructions and checks into documents
1
Write the instructions
Turn each path instruction into a Markdown file under
.coderabbit/instructions/. For example, .coderabbit/instructions/currency.md:.coderabbit/instructions/currency.md
2
Write the checks
Turn each custom check into a Markdown file under
.coderabbit/pre-merge-checks/. For example, .coderabbit/pre-merge-checks/currency-tests.md:.coderabbit/pre-merge-checks/currency-tests.md
3
Remove the inline copies
Delete the migrated definitions from the YAML, and check inherited definitions too. An instruction can otherwise apply twice, and an active inline check canât share a display name with a directory check.
Features V3 turns off
CodeRabbit doesnât convert built-in checks into Markdown checks. Decide which policy you still need and write it as a custom check. A replacement check isnât guaranteed to behave like the built-in check. Test passing and failing pull requests, and use a plan that includes custom checks.
Decide how inheritance works after migration
V3 files are sparse: omit a field to receive the inherited or default value.- Keep receiving parent settings
- Freeze current values
.coderabbit.yaml
Confirm settings managed elsewhere
V3 YAML doesnât hold these settings. An authorized administrator confirms each one in the web interface:- Early access and repository exceptions (
early_access) - Knowledge Base connections, scopes and privacy (
knowledge_base) - Chat integrations (
chat.integrations) - Finishing touches, post-merge actions and code generation instructions (
reviews.finishing_touches,reviews.post_merge_actions,code_generation) - Issue enrichment (
issue_enrichment) - Automatic-review exclusions by author or title (
reviews.auto_review.ignore_usernames,reviews.auto_review.ignore_title_keywords)
Check the result
1
Open a trusted test pull request
Use a code change that matches one of your instructions and checks.
2
Confirm the source
Comment
@coderabbitai configuration and check the V3 source and revision. The command doesnât prove that .coderabbit/ documents loaded.3
Read the review
Check that instructions affect it and every check reports as expected. Then fix a deliberately failing condition and confirm the re-review.
Roll back to V2
Restore the original V2 file with its field names and inline definitions. Changingversion: 3 to 2, or deleting version, doesnât reverse the migration. Revert directory documents you added if the restored inline definitions would duplicate them, and keep the ones that existed before. If an administrator changed settings managed outside the file during the migration, coordinate their rollback with that administrator. Then run the configuration command and confirm a completed review. See Check which configuration a review used.
Whatâs next
V3 reference
Every V3 key.
Instruction and check documents
Write the Markdown files.
Check the configuration used
Verify what a review used.