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

# Built-in Pre-Merge Checks

> Enforce quality gates and organization's custom requirements before pull requests are merged.

export const Hint = ({type, children, headline, tip, href, cta}) => {
  const TIPS = {
    learnings: {
      headline: "Learnings",
      tip: "Review preferences CodeRabbit learns from your chat conversations and applies automatically to future reviews.",
      cta: "Learn about Learnings",
      href: "/knowledge-base/learnings",
      content: "Learnings"
    },
    walkthrough: {
      headline: "PR Walkthrough",
      tip: "A structured comment posted by CodeRabbit at the top of every pull request, summarizing changes, sequence diagrams, review effort, and more.",
      cta: "Learn about PR Walkthroughs",
      href: "/pr-reviews/walkthroughs",
      content: "Walkthrough"
    },
    "finishing-touches": {
      headline: "Finishing Touches",
      tip: "Post-review agentic actions (Autofix, writing docstrings or unit tests, and more) you trigger from a PR comment or a checkbox in the Walkthrough.",
      cta: "See all Finishing Touches",
      href: "/finishing-touches",
      content: "Finishing Touches"
    },
    "coding-plan": {
      headline: "Coding Plan",
      tip: "A detailed, codebase-aware implementation plan CodeRabbit generates from an issue or description, ready to hand off to any coding agent.",
      cta: "Learn about Coding Plans",
      href: "/plan",
      content: "Coding Plan"
    },
    "knowledge-base": {
      headline: "Knowledge Base",
      tip: "The collected context sources CodeRabbit draws on during reviews: Learnings, Code Guidelines, issue trackers, connected MCP servers, and cross-repo analysis.",
      cta: "Explore the Knowledge Base",
      href: "/knowledge-base",
      content: "Knowledge Base"
    },
    "path-instructions": {
      headline: "Path Instructions",
      tip: "Custom review rules that only apply to files matching a glob pattern, e.g. 'src/controllers/**'.",
      cta: "Configure path instructions",
      href: "/configuration/path-instructions",
      content: "Path Instructions"
    },
    scope: {
      headline: "Scope",
      tip: "A named set of repositories, connections, and spend limits that controls what CodeRabbit Agent can access in a given Slack conversation.",
      cta: "Learn about Scopes",
      href: "/slack-agent/scopes",
      content: "Scope"
    }
  };
  const defaults = TIPS[type] || ({});
  return <Tooltip headline={headline ?? defaults.headline} tip={tip ?? defaults.tip} cta={cta ?? defaults.cta} href={href ?? defaults.href}>
      {children ?? defaults.content}
    </Tooltip>;
};

export const ProPlanBadge = ({tip = "This feature is available as part of the Pro, Pro+ and Enterprise plans. Please refer to our pricing page for more information about our plans and features.", title = "Pro Plan", cta = "Read more", href = "https://coderabbit.ai/pricing", disabled = false}) => {
  return <Tooltip tip={tip} cta={cta} href={href}>
        <Badge icon="shield-check" disabled={disabled || undefined}>
            {title}
        </Badge>
    </Tooltip>;
};

<ProPlanBadge />

Agentic Pre-Merge Checks provide automated validation of pull requests against standard quality metrics and organization-specific requirements. Use **Built-in Checks** for common requirements and add your own **Custom Checks** with natural language instructions tailored to your team’s policies. These AI-powered checks can be configured by an Admin user at the organization or repository level, and CodeRabbit automatically validates every pull request against these requirements.

## Why use Pre-Merge Checks?

* **Consistent standards:** Enforce naming, documentation, and change-management hygiene across every PR.
* **Safer merges:** Catch breaking API changes, security gaps, or policy violations before they land.
* **Team-specific guardrails:** Encode architectural patterns, compliance rules, or business logic as custom checks.
* **Faster reviews:** Surface blocking issues early in the PR <Hint type="walkthrough" /> so reviewers can act quickly.

## Built-in Checks

CodeRabbit includes four standard checks that address common organizational needs:

<CardGroup cols={2}>
  <Card title="Docstring Coverage" icon="file-code">
    Verify PR docstring coverage against a configurable threshold (80% by
    default)
  </Card>

  <Card title="Pull Request Title" icon="heading">
    Validate PR titles accurately reflect changes made and follow your specified
    requirements
  </Card>

  <Card title="Pull Request Description" icon="file-text">
    Verify descriptions follow the template specified in your Git platform
  </Card>

  <Card title="Issue Assessment" icon="link">
    Verify PRs address linked issues without containing out-of-scope changes
  </Card>
</CardGroup>

## Custom Checks

Go beyond built-in checks by defining your own validation logic using natural language instructions. Custom checks leverage AI to understand and validate complex requirements specific to your team's policies, such as:

* Detecting sensitive data in logs
* Enforcing documentation for breaking changes
* Validating database migration patterns
* Ensuring compliance with language migration policies

Custom checks are available on the **Pro+ plan and above**. Pro+ and Enterprise plans support up to 20 custom checks per organization.

Custom checks run in a secure, read-only sandbox and can access the PR diff, linked issues, and external context via [MCP tools](/integrations/mcp-servers). Learn more about [writing custom checks](/pr-reviews/custom-checks), including limitations and examples.

## Configuring Pre-merge Checks

### Enforcement Modes

Each check can be configured with one of three enforcement modes:

* `off`: Check is disabled
* `warning`: Display warnings but don't block merges (default)
* `error`: When paired with [Request Changes Workflow](/reference/configuration#param-request-changes-workflow), block merges until resolved or manually overridden

<Tip>
  Start new checks in `warning` mode to gather feedback, then move to `error`
  mode once your team is aligned on expectations.
</Tip>

### Configuration

Pre-Merge Checks can be configured via web interface or using `.coderabbit.yaml` file.

<Tabs>
  <Tab title="Web Interface" icon="browser">
    Configure Pre-Merge Checks through the CodeRabbit dashboard:

    <Steps>
      <Step title="Navigate to Settings">
        In CodeRabbit, go to **Settings → Pre-merge checks** (org or repo scope)
      </Step>

      <Step title="Configure Built-in Checks">
        Update configuration and enforcement modes for **Built-in Checks**
      </Step>

      <Step title="Add Custom Checks">
        Add **Custom Checks**:

        * **Name** (≤ 50 chars, unique within the org)
        * **Instructions** (≤ 1000 chars; natural language)
        * **Mode** (off | warning | error)
      </Step>

      <Step title="Apply Changes">
        Click Apply Changes to save. The new checks are applied to subsequent reviews.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Configuration File" icon="file-code">
    For version-controlled configuration, add checks to your `.coderabbit.yaml` file:

    ```yaml YAML icon=code wrap theme={null}
    reviews:
      pre_merge_checks:
        docstrings:
          mode: "error"
          threshold: 85
        title:
          mode: "warning"
          requirements: "Start with an imperative verb; keep under 50 characters."
        description:
          mode: "error"
        issue_assessment:
          mode: "warning"
        custom_checks:
          - name: "Undocumented Breaking Changes"
            mode: "warning"
            instructions: "Pass/fail criteria: All breaking changes to public APIs, CLI flags, environment variables, configuration keys, database schemas, or HTTP/GraphQL endpoints must be documented in the Breaking Change section of the PR description and in CHANGELOG.md. Exclude purely internal or private changes (e.g., code not exported from package entry points or explicitly marked as internal)."
    ```
  </Tab>
</Tabs>

## Results in the Walkthrough

Pre-Merge Check results appear alongside CodeRabbit's analysis in the PR **Walkthrough** with clear visual organization for quick assessment.

Results are organized into two tables:

* **Failed checks** — prominently displayed to show errors and warnings requiring attention
* **Passed checks** — expandable to review checks that were validated successfully

Each check displays:

* **Objective** — the name of the check being evaluated
* **Status** — one of:
  * ❌ Error — failed and will block merge when **Request Changes** is enabled
  * ⚠️ Warning — failed but non-blocking
  * ✅ Passed — requirements met
  * ❓ Inconclusive — incomplete instructions or insufficient information to decide
* **Explanation** — why the check passed or failed
* **Resolution** — what the author can do to remediate

### Unblocking a PR

If **Request Changes Workflow** is enabled and a check in **Error** mode fails, the PR is blocked until the issue is resolved or you explicitly ignore it. To ignore, select the **Ignore failed checks** checkbox in the PR Walkthrough. The PR is then unblocked and the affected rows are tagged **\[IGNORED]** for traceability.

<Note>
  The override applies only to that PR. Future PRs will still enforce checks as
  configured.
</Note>

<Note>
  You can restrict who can ignore failed checks by setting
  `reviews.pre_merge_checks.override_requested_reviewers_only: true` (default: `false`). When
  enabled, only requested reviewers (not the PR author) can use the checkbox
  or `@coderabbitai ignore pre-merge checks`, and CodeRabbit records who
  performed the override for auditability.
</Note>

## Manual commands

Trigger pre-merge checks manually using chat commands:

### Run All Checks

```md theme={null}
@coderabbitai run pre-merge checks
```

This reruns all configured checks and updates results in the walkthrough.

### Test Custom Check

```dotenv icon=text wrap theme={null}
@coderabbitai evaluate custom pre-merge check --name <check_name> --instructions <text> [--mode <error|warning>]
```

Tests custom check logic before saving to configuration.

### Ignore failures

```md theme={null}
@coderabbitai ignore pre-merge checks
```

Manually ignore failed checks and unblock the PR.

> See [**Manage code reviews**](/guides/commands) for more commands and behaviors.