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

# Validate and test a configuration change

> Check a configuration file for mistakes and see the effect of a change before it reaches your team's pull requests.

Validate a change to catch typos and wrong types, then test it to see how reviews behave. Validation checks the file against the schema. Testing runs a review with the new configuration.

## Before you start

* Know which [schema version](https://docs.coderabbit.ai/configuration/file.md#choose-a-schema-version) your file uses. Your editor, the CLI and the web app's YAML editor check against the V2 schema.
* Know which branch your repository reads configuration from. See [Choose the configuration branch](https://docs.coderabbit.ai/configuration/branch.md).
* To check the result of any step, use [Check which configuration a review used](https://docs.coderabbit.ai/configuration/guides/check-effective-configuration.md).

## Validate in your editor

Put the schema comment on the first line of the file so editors that use the YAML language server autocomplete keys and flag mistakes.

```yaml .coderabbit.yaml theme={null}
# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
```

> [!WARNING]
>
> The published V2 schema declares no `version` property and rejects unknown top-level keys. Your editor flags `version` (including `version: 2`) and `remote_config`, and it flags every V3 file. CodeRabbit itself accepts `version: 2` and an absent `version` at review time.

## Validate with the CLI

Run the validator in a repository that has a `.coderabbit.yaml` or `.coderabbit.yml` file:

```bash theme={null}
coderabbit config validate
coderabbit config validate path/to/.coderabbit.yaml
```

The command prints line-numbered errors and exits with code `1` when validation fails. Add `--json` or `--agent` for machine-readable output, for example in CI.

> [!NOTE]
>
> The command downloads the schema from `www.coderabbit.ai`, so allow that host on restricted networks. It needs CLI 0.7.1 or later and doesn't appear in `--help`. It validates against the V2 schema only, so a file with `version` or `remote_config` fails.

## Validate in the web interface

The **YAML editor** view of the settings page validates YAML as you type and blocks saving until you fix the errors. It checks against the V2 schema that ships with the web app, and an unknown key is an error, so a `version` key is flagged there too. Organizations in the V3 limited preview get a separate V3 editor that checks against the V3 schema. A custom [Configuration source](https://docs.coderabbit.ai/configuration/branch.md) is validated when you save it: if CodeRabbit can't read the branch or its YAML is invalid, the previous source stays active.

## Validate in the browser

Paste a configuration into the editor below to check its YAML before you commit it.

[YAML Validator](https://yaml-editor-ochre.vercel.app/embed)

## Type-check a TypeScript configuration

With the SDK installed and the file in your TypeScript project, run the compiler in CI:

```bash theme={null}
npx tsc --noEmit
```

Unknown keys, misspelled options and invalid values are type errors. At review time, CodeRabbit validates the evaluated output against the same schema as YAML. See [TypeScript configuration](https://docs.coderabbit.ai/configuration/typescript.md).

## Fix version errors

> [accordion] Version errors and what they mean
>
> | Message | Cause |
> | - | - |
> | Configuration schema version must be the number 2 or 3 | `version` isn't a number, for example `"3"` |
> | Configuration schema version N is not supported by this build | `version` is another number, or V3 isn't available to your repository |
>
> CodeRabbit doesn't retry a file that fails V3 validation as V2. The file yields no settings, and the review uses the next layers. Fix the error or restore the V2 file.

## Test in the pull request that changes the file

**1. Change the file on a branch**

Edit `.coderabbit.yaml` and open a pull request.

**2. Read the review**

Check **Source mode** and **Commit** in **Run configuration** first. The review uses your edit only for a trusted pull request under **Auto**, or under **Default branch** with **Allow configuration changes from trusted PRs** on. Otherwise, run a [preview review](#run-a-preview-review-from-a-draft-pull-request). It needs a draft pull request from a branch in the same repository and write access, so ask a collaborator with write access when you don't have it. Then check the pull request summary for a parsing warning, and judge the review against what you changed.

**3. Merge when it looks right**

Other pull requests keep their current configuration until the change merges.

Whether the pull request's own file applies depends on the repository's [configuration source](https://docs.coderabbit.ai/configuration/branch.md). A trusted pull request comes from a branch in the same repository, and its author meets your Git provider's [trust rule](https://docs.coderabbit.ai/configuration/branch.md#who-counts-as-trusted).

| Configuration source | The pull request's own file applies when |
| - | - |
| **Auto** (default) | The pull request is trusted. Fork and other pull requests use the file from the target branch. |
| **Default branch** with **Allow configuration changes from trusted PRs** on | The pull request is trusted and changes, adds, deletes or renames a configuration file. **Source mode** then shows `Trusted PR override`. |
| **Default branch** with the toggle off | Never. Reviews use the default branch's latest file. |
| **Custom** | Never. Reviews use the file from the custom branch. |

If the selected source can't be read, the review falls back to **Auto** and shows a warning.

## Run a preview review from a draft pull request

Comment exactly this on a draft pull request:

```text theme={null}
@coderabbitai review --preview-config
```

CodeRabbit runs an isolated full review with the configuration not yet merged from the pull request branch. The result is labeled non-authoritative, automatic approvals stay off, and the pull request's review state and status don't change.

> [!NOTE]
>
> You need write access. The pull request must be a [trusted](https://docs.coderabbit.ai/configuration/branch.md#who-counts-as-trusted) draft from a branch in the same repository, and its configuration must parse. Help lists the command for GitHub and GitHub Enterprise Server only.

## Compare before and after in the web interface

When you select **Apply changes** in a repository's settings, the **Review changes** dialog opens before anything is saved.

* **Your changes** lists each edited setting with its saved value, your edit and its impact.
* On GitHub Cloud, a **Current** and **After submit** toggle shows the effective YAML before and after the change, with a full YAML comparison and the configuration sources before and after. Other platforms show the list of changes only.

Select **Submit changes** to save, or **Back to editing**. Organization defaults and global overrides skip this dialog: they save after **Apply changes** in a confirmation dialog, without a before-and-after comparison. See [Save and review changes](https://docs.coderabbit.ai/configuration/web-app.md#save-and-review-changes).

## Try a setting on one review

Add a fenced YAML block after the command to apply it to a single review:

````text theme={null}
@coderabbitai review --with-config
```yaml
inheritance: true
reviews:
  profile: assertive
```
````

Without `inheritance: true`, the block replaces the resolved repository configuration, and omitted keys take schema defaults. It can't change approval policy or risk instructions. See [Change settings for one pull request](https://docs.coderabbit.ai/configuration/guides/one-pull-request.md).

## Preview through the API

`preview_repository_configuration` resolves the effective YAML for settings you supply and saves nothing. See [Automate configuration with the API, MCP and CLI](https://docs.coderabbit.ai/configuration/guides/automate.md).

## Check the result

Comment `@coderabbitai configuration` on the pull request and confirm the layers and values you expect. See [Check which configuration a review used](https://docs.coderabbit.ai/configuration/guides/check-effective-configuration.md).

## What's next

> [card] [Check the configuration used](https://docs.coderabbit.ai/configuration/guides/check-effective-configuration.md)
>
> See which layer supplied each value.

> [card] [Change one pull request](https://docs.coderabbit.ai/configuration/guides/one-pull-request.md)
>
> Override settings for a single review.

> [card] [Fix settings not applied](https://docs.coderabbit.ai/configuration/guides/troubleshoot.md)
>
> Diagnose a change that has no effect.


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