Skip to main content
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. The built-in checks and YAML examples on this page apply to configuration V2. V3 disables built-in title, description, and issue-assessment checks and has no pre_merge_checks YAML section. V3 repositories can define custom checks in .coderabbit/pre-merge-checks/; see migrate instructions and checks before replacing a built-in policy.

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 so reviewers can act quickly.

Built-in Checks

CodeRabbit includes three standard checks that address common organizational needs:

Pull Request Title

Validate PR titles accurately reflect changes made and follow your specified requirements

Pull Request Description

Verify descriptions follow the template specified in your Git platform

Issue Assessment

Verify PRs address linked issues without containing out-of-scope changes

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 Team plan and above. See Plans and pricing — Custom Pre-Merge Checks for current limits. Custom checks run in a secure, read-only sandbox and can access the PR diff, linked issues, and external context via MCP tools. Learn more about writing 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 Automatic Approvals, block merges until resolved or manually overridden
These merge controls apply to built-in checks, inline custom checks, and directory checks configured with report: coderabbit. For directory checks configured with report: platform, mode controls the check conclusion, and GitHub repository rules control whether it is required before merge. This remains true if a permission problem causes CodeRabbit to show the result in the Walkthrough. See GitHub Check Runs.
Start new checks in warning mode to gather feedback, then move to error mode once your team is aligned on expectations.

Configuration

Pre-Merge Checks can be configured via the web interface or using the .coderabbit.yaml file. On GitHub Cloud with CodeRabbit Cloud, configuration directories also let you define custom checks in .coderabbit/pre-merge-checks/. See Define a check in Markdown for an example and the supported front matter.
Configure Pre-Merge Checks through the CodeRabbit dashboard:
1

Navigate to Settings

In CodeRabbit, go to Settings → Pre-merge checks (org or repo scope)
2

Configure Built-in Checks

Update configuration and enforcement modes for Built-in Checks
3

Add Custom Checks

Add Custom Checks:
  • Name (≤ 50 chars, unique within the org)
  • Instructions (≤ 10,000 chars; natural language)
  • Mode (off | warning | error)
4

Apply Changes

Click Apply Changes to save. The new checks are applied to subsequent reviews.

GitHub Check Runs

A custom check defined in .coderabbit/pre-merge-checks/ uses report: platform by default. On GitHub Cloud with CodeRabbit Cloud, CodeRabbit publishes a separate Check Run for that definition. Set report: coderabbit in its front matter to use the Walkthrough instead. This choice does not change the reporting of built-in checks or existing inline YAML checks. A warning failure is neutral, but an execution error is not a pass. Read the check’s explanation to see whether to change the code, correct the definition, or run the check again.

Missing GitHub Checks permission

Creating or updating a Check Run requires the GitHub App’s Checks repository permission set to Read and write. See GitHub’s Check Runs permissions. If CodeRabbit confirms that this permission is missing, the custom check still runs. Its result appears in the Walkthrough with a permission notice, including when permission is lost before the final Check Run update. The check remains configured as report: platform: this fallback does not enable CodeRabbit’s native merge blocking or Ignore controls for it. Unrelated API errors, rate limits, and timeouts do not trigger this permission fallback. Ask the GitHub account or organization owner to approve the CodeRabbit App’s updated permissions, then run @coderabbitai run pre-merge checks again. Once Checks write permission is available, CodeRabbit resumes Check Run reporting. You do not need to change the check’s front matter.
The Walkthrough result cannot satisfy a required GitHub Check Run. A missing or unfinished required check can still block the merge. An existing Check Run, including a previous pass, may be out of date because CodeRabbit cannot update it without permission. Restore the permission and rerun the check before relying on its GitHub status. CodeRabbit does not remove or bypass your branch protection or ruleset requirements.

Require a check before merge

Publishing a Check Run does not make it a required check. Configure the required status check in your GitHub branch protection or ruleset. CodeRabbit does not change these repository rules, and this enforcement does not require CodeRabbit Automatic Approvals. Select the actual check name shown in GitHub. It has the form CodeRabbit / <identity suffix>; the definition’s name appears as the result title, not as the status-check name. The identity is based on the repository, definition kind, directory scope, and id. Changing name or moving the Markdown file within the same scope preserves that identity. Changing id or directory scope creates a different identity, so review your required-check rules after such a change. After CodeRabbit loads the complete directory definitions, it reports checks that do not apply as skipped. A review that stops before loading the directory might not report those checks. Before requiring a check, test pull requests with matching paths, without matching paths, and with reviews that are skipped by your settings. Update or remove the required-check rule before you delete a definition, change its id or scope, or switch it to report: coderabbit. Otherwise, GitHub can wait for a check name that CodeRabbit no longer reports. See GitHub’s required status check troubleshooting. The Walkthrough Ignore checkbox and the CodeRabbit ignore command apply to native CodeRabbit results. They do not clear a required GitHub Check Run. GitHub repository rules continue to apply.

Results in the Walkthrough

Built-in checks, inline custom checks, and directory checks with report: coderabbit appear alongside CodeRabbit’s analysis in the PR Walkthrough. Directory checks with report: platform appear as GitHub Check Runs, or in the Walkthrough with a notice when Checks write permission is missing. These fallback results do not gain the native merge controls described below. 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 Automatic Approvals is enabled
    • ⚠️ Warning — failed but non-blocking
    • ✅ Passed — requirements met
    • ❓ Inconclusive — incomplete instructions, insufficient information, or analysis that could not be completed; does not block the pull request
  • Explanation — why the check passed or failed
  • Resolution — what the author can do to remediate
The results tables show a preview of each field. For each affected check, CodeRabbit appends the complete Explanation and Resolution content in a per-check Full details section. GitHub and GitLab pull requests render Full details as an expandable section; platforms without expandable HTML receive the same complete content as a block-level plain-text fallback.

Unblocking a PR

If Automatic Approvals 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 on GitHub, select the Ignore checkbox in the PR Walkthrough. On other Git providers, use @coderabbitai ignore pre-merge checks. The PR is then unblocked and the affected rows are tagged [IGNORED] for traceability.
The override applies only to that PR. Future PRs will still enforce checks as configured.
You can restrict who can ignore failed checks by setting reviews.pre_merge_checks.override_requested_reviewers_only: true (default: false). When enabled, the checkbox reads Ignore (reviewers only), and both the checkbox and @coderabbitai ignore pre-merge checks are restricted: individually requested reviewers can use them. On GitHub, members of a requested reviewer team can also use these overrides. So can people who submitted a review, when the review’s GitHub author association is OWNER, MEMBER, or COLLABORATOR. The pull request author cannot override the checks, and CodeRabbit records who performed the override for auditability.

Manual commands

Trigger pre-merge checks manually using chat commands:

Run All Checks

Runs the configured pre-merge checks on the pull request again.
  • Post in: A pull request comment
Native results appear in the Walkthrough; directory checks with report: platform update their GitHub Check Runs, or show a Walkthrough result when Checks write permission is missing.

Test Custom Check

Test custom check logic before saving it to configuration. Runs a custom pre-merge check on the pull request without adding it to your configuration.
  • Post in: A pull request comment
option
required
What the check should verify, in plain language. Quote text that contains spaces.
option
required
The check’s title.
option
error or warning. Defaults to error.

Ignore failures

Manually ignore failed checks and unblock the PR. Overrides failing pre-merge checks so they don’t block CodeRabbit’s approval.
See Manage code reviews for more commands and behaviors.