Skip to main content
V3 is a limited preview of a new configuration schema. It reorganizes the review settings, keeps instructions and checks in Markdown under .coderabbit/, and manages some settings outside the file. A migration changes more than the version number.

Before you start

Adding version: 3, creating .coderabbit/, or enabling early access doesn’t give your organization access to V3. Start only after CodeRabbit confirms access. Otherwise keep V2.
  • The procedure covers the .coderabbit.yaml or .coderabbit.yml file 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 V2 reviews 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
Keep reporting on if a branch rule requires the 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.
Keep copies for rollback and for branches that still use V2. See Instruction and check documents.

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.
.coderabbit.yaml
Explicit values win over inherited ones, even when they equal the default.

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)
Don’t invent YAML keys for them. Some transfers need help from CodeRabbit during the preview.

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.
If the V3 file is invalid, ordinary reviews can continue with another configured source. Until you fix the file, CodeRabbit turns off automatic approvals and approval by the pull request author, lets only requested reviewers override checks, blocks chat for people outside the organization, and turns off Knowledge Base features that need stored data.

Roll back to V2

Restore the original V2 file with its field names and inline definitions. Changing version: 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.