> ## 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.

# Migrate configuration to V3

> Move a repository's .coderabbit.yaml from schema V2 to V3: map the keys, move instructions and checks into .coderabbit/, and verify and roll back the change.

Early Access (This feature is in early access. Enable it by setting `early_access: true` in your `.coderabbit.yaml`, or by toggling Early Access on the web interface.)

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

> [!WARNING]
>
> 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](https://docs.coderabbit.ai/reference/configuration-v3.md). 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](https://docs.coderabbit.ai/configuration/examples#use-v3-and-directory-documents).

### Keys that move

| V2 key | V3 key | Notes |
| - | - | - |
| `language`, `inheritance` | `language`, `inheritance` | Same path |
| `tone_instructions` | `fun.tone_instructions` | |
| `chat.art` | `fun.art` | V3 default is off |
| `reviews.in_progress_fortune` | `fun.in_progress_fortune` | V3 default is off |
| `chat.allow_non_org_members` | `reviews.output.chat.allow_non_org_members` | |
| `reviews.profile` | `reviews.behavior.profile` | |
| `reviews.path_filters` | `reviews.behavior.path_filters` | |
| `reviews.merge_risk_instructions` | `reviews.behavior.merge_risk_instructions` | |
| `reviews.security_risk_instructions` | `reviews.behavior.security_risk_instructions` | |
| `reviews.auto_approvals` | `reviews.behavior.auto_approvals` | Every field moves with the object |
| `reviews.request_changes_workflow` | `reviews.behavior.auto_approvals.enabled` | Legacy V2 alias of `reviews.auto_approvals.enabled` |
| `reviews.allow_author_approval` | `reviews.behavior.auto_approvals.allow_author_approval` | Legacy V2 alias of `reviews.auto_approvals.allow_author_approval` |
| `reviews.pre_merge_checks.override_requested_reviewers_only` | `reviews.behavior.auto_approvals.override_requested_reviewers_only` | |
| `reviews.review_progress`, `reviews.commit_status` | `reviews.behavior.status.progress_updates` | One switch for both formats. On when either V2 key is on. See [Progress reporting](#progress-reporting) |
| `reviews.fail_commit_status` | `reviews.behavior.status.fail_on_error` | |
| `reviews.high_level_summary`, `reviews.high_level_summary_in_walkthrough` | `reviews.output.summary.placement` | `off` when `high_level_summary` is `false`. Otherwise `walkthrough` when `high_level_summary_in_walkthrough` is `true`, and `description` when it isn't |
| `reviews.high_level_summary_placeholder` | `reviews.output.summary.placeholder` | |
| `reviews.high_level_summary_instructions` | `reviews.output.summary.instructions` | |
| `reviews.review_info`, `reviews.review_details` | `reviews.output.review_info`, `reviews.output.review_details` | |
| `reviews.collapse_walkthrough` | `reviews.output.walkthrough.collapse` | |
| `reviews.review_status` | `reviews.output.walkthrough.review_status` | |
| `reviews.changed_files_summary` | `reviews.output.walkthrough.changed_files_summary` | |
| `reviews.related_issues`, `reviews.related_prs` | `reviews.output.walkthrough.related_issues`, `reviews.output.walkthrough.related_prs` | |
| `reviews.suggested_labels`, `reviews.auto_apply_labels` | `reviews.output.metadata.labels.mode` | `apply` when `auto_apply_labels` is `true`, `suggest` when only `suggested_labels` is `true`, `off` otherwise. `apply` also suggests labels |
| `reviews.labeling_instructions` | `reviews.output.metadata.labels.instructions` | |
| `reviews.mutually_exclusive_groups` | `reviews.output.metadata.labels.mutually_exclusive_groups` | |
| `reviews.suggested_reviewers`, `reviews.auto_assign_reviewers` | `reviews.output.metadata.reviewers.mode` | `apply` when `auto_assign_reviewers` is `true`, `suggest` when only `suggested_reviewers` is `true`, `off` otherwise. `apply` also suggests reviewers |
| `reviews.suggested_reviewers_instructions` | `reviews.output.metadata.reviewers.instructions` | |
| `reviews.auto_review.enabled`, `.description_keyword`, `.labels`, `.drafts`, `.base_branches` | Same path under `reviews.auto_review` | |
| `reviews.auto_review.auto_incremental_review` | `reviews.auto_review.incremental_review` | |
| `reviews.auto_review.auto_pause_after_reviewed_commits` | `reviews.auto_review.pause_after_reviewed_commits` | |
| `reviews.tools.*` | `reviews.tools.*` | Same 59 tools and fields |

### Keys that become Markdown documents

| V2 key | V3 location |
| - | - |
| `reviews.path_instructions` | `.coderabbit/instructions/*.md` |
| `reviews.pre_merge_checks.custom_checks` | `.coderabbit/pre-merge-checks/*.md` |

See [Move instructions and checks into documents](#move-instructions-and-checks-into-documents).

### Keys without a V3 key

| V2 key | What happens in V3 |
| - | - |
| `reviews.poem`, `reviews.sequence_diagrams`, `reviews.estimate_code_review_effort`, `reviews.assess_linked_issues` | Fixed off. See [Features V3 turns off](#features-v3-turns-off) |
| `reviews.enable_prompt_for_ai_agents`, `chat.auto_reply` | Fixed on |
| `reviews.pre_merge_checks.title`, `.description`, `.issue_assessment`, `.docstrings` | Off. Write a custom check to replace one |
| `early_access`, `knowledge_base`, `chat.integrations`, `reviews.finishing_touches`, `reviews.post_merge_actions`, `code_generation`, `issue_enrichment`, `reviews.auto_review.ignore_title_keywords`, `reviews.auto_review.ignore_usernames` | Managed outside the file. See [Confirm settings managed elsewhere](#confirm-settings-managed-elsewhere) |
| `enable_free_tier`, `remote_config`, `reviews.abort_on_close`, `reviews.disable_cache`, `reviews.slop_detection`, `reviews.auto_title_placeholder`, `reviews.auto_title_instructions` | No V3 key. Check the resolved value with `@coderabbitai configuration` after you migrate |

### 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.

| Earlier preview key | V3 key | Notes |
| - | - | - |
| `reviews.behavior.request_changes_workflow` | `reviews.behavior.auto_approvals.enabled` | Configuration error |
| `reviews.behavior.allow_author_approval` | `reviews.behavior.auto_approvals.allow_author_approval` | Configuration error |
| `pre_merge_checks.override_requested_reviewers_only` | `reviews.behavior.auto_approvals.override_requested_reviewers_only` | Configuration error |
| `reviews.output.comments.chat.allow_non_org_members` | `reviews.output.chat.allow_non_org_members` | Configuration error |
| `reviews.output.walkthrough.review_info`, `reviews.output.walkthrough.review_details` | `reviews.output.review_info`, `reviews.output.review_details` | Reviews still read them. The published V3 schema rejects them |
| `reviews.behavior.status.legacy_commit_status` | `reviews.behavior.status.progress_updates` | Reviews still read it. The published V3 schema rejects it. See [Progress reporting](#progress-reporting) before you remove it |

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`](https://docs.coderabbit.ai/reference/configuration-v3#param-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:

> [tab] .coderabbit.yaml
>
> ```yaml .coderabbit.yaml theme={null}
> version: 3
> reviews:
>   behavior:
>     status:
>       progress_updates: true
> ```

> [tab] Web UI
>
> In **Review settings**, select the repository or **Organization defaults**. Open **Review behavior**, turn on **Progress updates** under **Status**, select **Apply changes** and confirm. Changing **Progress updates** removes a saved `legacy_commit_status` value.

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](https://docs.coderabbit.ai/pr-reviews/status-check.md#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`:

```markdown .coderabbit/instructions/currency.md theme={null}
---
id: currency
paths:
  - "src/payments/**"
---

Keep monetary amounts in integer cents. Flag calculations that mix cents with decimal currency amounts.
```

**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`:

```markdown .coderabbit/pre-merge-checks/currency-tests.md theme={null}
---
id: currency-tests
name: Currency test coverage
paths:
  - "src/payments/**"
mode: warning
report: platform
---

Pass if changes to currency calculations include tests for rounding and negative amounts. Fail if either case is missing.
```

**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](https://docs.coderabbit.ai/configuration/documents.md).

## Features V3 turns off

| Feature | V3 behavior | Replacement |
| - | - | - |
| Poem, sequence diagrams, code review effort estimates, linked issue assessment | Fixed off; V2 keys are not accepted | None |
| Prompt for AI agents, chat auto-reply | Fixed on | None |
| Built-in title, description, docstrings and issue assessment checks | Off, even when a V2 parent enables them | A custom check in `.coderabbit/pre-merge-checks/` |
| A `pre_merge_checks` key anywhere in a V3 file | Configuration error | Documents in `.coderabbit/pre-merge-checks/` |
| Art and in-progress fortunes | Off by default. An inherited or authored `true` turns them on | `fun.art`, `fun.in_progress_fortune` |

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.

> [tab] Keep receiving parent settings
>
> ```yaml .coderabbit.yaml theme={null}
> version: 3
> inheritance: true
> reviews:
>   behavior:
>     profile: assertive
> ```
>
> Explicit values win over inherited ones, even when they equal the default.

> [tab] Freeze current values
>
> ```yaml .coderabbit.yaml theme={null}
> version: 3
> inheritance: false
> # Copy every value you want to keep from the recorded configuration.
> ```
>
> Pinned values don't follow later changes to organization defaults.

## 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.

> [!WARNING]
>
> 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](https://docs.coderabbit.ai/configuration/guides/check-effective-configuration.md).

## What's next

> [card] [V3 reference](https://docs.coderabbit.ai/reference/configuration-v3.md)
>
> Every V3 key.

> [card] [Instruction and check documents](https://docs.coderabbit.ai/configuration/documents.md)
>
> Write the Markdown files.

> [card] [Check the configuration used](https://docs.coderabbit.ai/configuration/guides/check-effective-configuration.md)
>
> Verify what a review used.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.