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
Configuring Pre-merge Checks
Enforcement Modes
Each check can be configured with one of three enforcement modes:off: Check is disabledwarning: Display warnings but don’t block merges (default)error: When paired with Automatic Approvals, block merges until resolved or manually overridden
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.
- Web Interface
- Configuration File
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 asreport: 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.
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 formCodeRabbit / <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 withreport: 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
- 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
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
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
Ignore failures
Manually ignore failed checks and unblock the PR. Overrides failing pre-merge checks so they don’t block CodeRabbit’s approval.- Post in: A pull request comment
- When
reviews.pre_merge_checks.override_requested_reviewers_onlyis enabled, only reviewers of the pull request can use it, not its author.
See Manage code reviews for more commands and behaviors.