Developers: 6 step checklist to fix blocked merges and add Veridical

Required status checks block a pull request from merging until the checks you designate report back success, neutral, or skipped on the current commit. They live inside branch protection rules or rulesets, can be pinned to a specific source app for provenance, and are the mechanism most teams rely on to stop broken or unreviewed code from reaching a protected branch. Most merge blocks trace back to a stale commit, a failing or misnamed check, or a misconfigured check source.

TL;DR:

• Ensuring the correct check source is pinned is crucial for security and compliance checks to prevent untrusted workflows from satisfying the gate.
• Strict mode enforces checks to be up-to-date with the base branch, reducing merge conflicts and integration issues, especially in high-churn repositories.
• Checks, which include logs and annotations, are preferable over commit statuses for diagnosing test failures or security issues.
• A common reason for blocked merges is a check tied to an outdated commit SHA or a name collision across workflows, which can be fixed by verifying the check’s current state and unique naming.
• Regularly reviewing and adjusting required checks and their sources, especially in growing teams, helps maintain an effective balance between velocity and safety.

Table of Contents

• What required status checks are and where they live
• How to enable and configure required status checks
• Strict vs loose required status checks and merge queue implications
• Checks vs commit statuses: what to prefer and why it matters
• Troubleshooting blocked merges: a checklist to diagnose and fix common causes
• Practical best practices and team policies for reliable required status checks
• How evidence-based code review complements required status checks
• Balancing velocity and safety in required status checks
• Strengthen your merge gate with Veridical
• FAQ
• Sources

What required status checks are and where they live

A required status check is either a check run or a commit status that GitHub treats as a gate on a protected branch. Both mechanisms produce a result, but they come from different sources and carry different levels of detail, and either one can be marked required. According to GitHub’s documentation on protected branches, a pull request cannot merge until every required check reports a success, neutral, or skipped conclusion on the head commit.

You configure these gates in one of two places; this enterprise platform comparison offers useful background on where required status checks and similar features are configured across platforms:

• Repository Settings → Branches → Branch protection rules, the classic interface most teams already know.
• The newer rulesets interface, which applies rules across multiple branches or repositories at once and supports layered enforcement.

When you pin an “expected source” app to a required check, only reports from that app satisfy the requirement. This matters because it stops a same-named status from an untrusted workflow or integration from accidentally (or deliberately) satisfying a gate meant for your trusted CI system.

How to enable and configure required status checks

Setting up required status checks takes a few minutes, but the choices you make determine how reliable the gate actually is.

1. Go to your repository’s Settings, select Branches (or Rules → Rulesets for the newer flow), and create or edit a protection rule for the target branch.
2. Enable Require status checks to pass before merging.
3. Search for and select the specific check names you want to enforce. These names must match the job or workflow name exactly as GitHub reports them.
4. If you want provenance guarantees, set the expected source for a check to a specific app rather than leaving it open to “any source,” a setting described in GitHub’s ruleset rules reference.
5. Save the rule and confirm it applies to the correct branch pattern.

Pinning an expected source app is worth the extra step for any check tied to security scanning, deployment gating, or compliance sign-off, since it prevents a differently sourced report with a matching name from slipping through.

Job-name uniqueness deserves its own attention. GitHub’s guidance on protected branches notes that identical job names across different workflows produce ambiguous results: GitHub cannot reliably tell which workflow’s report should satisfy the requirement, and a required check can appear to hang or fail for reasons that have nothing to do with your code.

Pro Tip: Prefix job names with the workflow or team that owns them (for example, “backend / unit-tests”) so no two pipelines ever collide on the same check name.

Strict vs loose required status checks and merge queue implications

GitHub gives you two operational modes once a check is required, and the choice has real consequences for both safety and build volume.

• Strict mode requires your branch to be up to date with the base branch before merging, which forces a fresh build against the latest base commit and catches integration problems before they land, as described in GitHub’s documentation on protected branches.
• Loose mode skips that freshness requirement, which means fewer rebuilds but a real risk that a branch merges cleanly against an outdated base and breaks immediately afterward.
• Merge queues add another layer: queued merges run through a separate testing context, and workflows must include a merge_group trigger for checks to run and report against the queue, according to GitHub’s troubleshooting guidance. Without that trigger, a queued pull request can stall indefinitely because the required check is never reported for the queue’s context.

High-churn repositories tend to need strict mode and a merge queue together. Low-traffic repositories with infrequent base changes can often tolerate loose mode without much added risk.

Checks vs commit statuses: what to prefer and why it matters

Checks and commit statuses both produce a pass or fail signal, but they are not interchangeable in what they tell you.

• Checks (check runs), typically produced by GitHub Apps or Actions workflows, carry logs, annotations, and line-level feedback that surface directly in the GitHub UI, per GitHub’s documentation on status checks.
• Commit statuses are a simpler binary or ternary signal, useful for lightweight gates where you only need to know that something ran and passed.
• Checks make debugging faster because a failing job points you to the exact log line or annotated code location, while a failing status just tells you something went wrong somewhere.

For anything that matters, a security scan, a test suite, a build pipeline, prefer checks over commit statuses. Reserve statuses for trivial signals where richer diagnostics would be overkill, such as a basic “deployment started” ping.

Pro Tip: If a required gate is still a commit status and you find yourself digging through external logs to understand a failure, that is a sign it belongs in a check run instead.

Troubleshooting blocked merges: a checklist to diagnose and fix common causes

Most blocked merges resolve once you work through a short, repeatable checklist instead of guessing.

1. Confirm the required check actually completed on the current head commit SHA. GitHub’s troubleshooting documentation notes that a check tied to an older commit does not satisfy the requirement for a newer head, a common issue after a rebase or a new commit to the base branch.
2. Check that the required check’s name matches exactly and is unique across workflows, since a name collision produces an ambiguous result.
3. If an expected source app is pinned, verify the check was actually posted by that app. If no app is pinned, treat “any source” as a deliberate choice, not a default, since it opens the gate to any workflow using that check name.
4. If strict mode is enabled, rebase onto or merge in the base branch, then wait for checks to re-run against the updated head.
5. Look for jobs that were skipped rather than run. GitHub’s status checks reference notes that a skipped conclusion is often treated like success for required checks, which can mask a real coverage gap when path filters or conditional logic quietly skip a job.
6. For repositories using a merge queue, confirm your workflows include a merge_group trigger. Without it, checks never run for the queue context and the merge stalls with no clear failure message.

A skipped job reporting as success is one of the most common silent gaps teams encounter, according to GitHub’s reference documentation on status checks; auditing your if conditions and path filters periodically catches cases where a check passes without actually testing anything.

Practical best practices and team policies for reliable required status checks

A few organizational habits keep required checks predictable instead of a recurring source of confusion.

• Enforce unique, stable job names across every workflow in the organization, not just within a single repository.
• Maintain a short, approved list of apps allowed to post required checks, and pin that expected source for anything security- or compliance-related.
• Document in your internal wiki or engineering handbook whether a given repository uses strict or loose gating, and the reasoning behind that choice.
• Adopt a merge queue for repositories with frequent base-branch changes and high pull request volume, since loose gating in that environment invites silent breakage.
• Spell out which checks are required and why in your CONTRIBUTING.md and pull request template, so contributors are not surprised by a gate they did not expect.

Pro Tip: Revisit your required checks list every quarter. Checks that made sense for a five-person team often need tightening, loosening, or outright replacement as your test suite and headcount grow.

How evidence-based code review complements required status checks

Required status checks are good at enforcing that something ran and passed. They say little about whether the code itself is safe to merge. We built Veridical to close that gap: our reviews produce verified findings backed by inline evidence, and a calibrated advisory score projected from real-defect F1 metrics, which teams can publish as a check and add to their required list, giving pull requests a test-agnostic quality gate alongside their existing CI. Details on how this fits into a GitHub workflow are on our AI code review product page.

Balancing velocity and safety in required status checks

Required status checks are safeguards, not finish lines. Teams that treat strictness as a one-time setting tend to drift either toward excessive friction or quiet risk as test coverage and team size change. Watch your CI telemetry, revisit strict versus loose mode, and adjust which checks are required as your repository matures. A gate configured for a five-person team rarely fits the same team at fifty.

— Łukasz

Strengthen your merge gate with Veridical

CI checks confirm your tests ran. They do not confirm that the change itself is safe, which is a different question entirely. We analyze the actual code change, including the callers, interfaces, and dependencies it touches, and return verified findings with concrete evidence plus a calibrated advisory score you can wire directly into your required status checks as an additional, test-agnostic gate.

Open-source maintainers can run the tool for free on public repositories through our open-source program. Teams evaluating it for private repositories can compare the Launch tier, Standard, and Pro plans. Check pricing on the website for current details. Check pricing for the details that fit your review volume.

FAQ

How do I enable required status checks in GitHub?

Go to Settings → Branches, create or edit a branch protection rule for the target branch, and turn on “Require status checks to pass before merging.” Then search for and select the specific check names you want enforced, as outlined in GitHub’s documentation on protected branches.

Why are my GitHub required status checks not running?

The most common causes are a check tied to an outdated commit SHA rather than the current head, a job name that collides with another workflow, or a merge queue missing the merge_group trigger needed for queued checks to report. GitHub’s troubleshooting guide walks through each of these cases in detail.

Does GitHub require status checks to pass before merging branches?

Only if you configure them as required in a branch protection rule or ruleset. Once set, a pull request cannot merge until each required check reports success, neutral, or skipped on the current head commit, per GitHub’s protected branches documentation.

How do I check my pull requests?

Open the pull request on GitHub and review the checks panel near the bottom of the conversation tab, which lists every check run and commit status along with its conclusion. For a deeper, evidence-based look at the change itself rather than just pass or fail signals, our AI code review tool adds verified findings and an advisory score alongside your existing checks.

Sources

• About protected branches
• Troubleshooting required status checks

Recommended

• How Veridical beats the leaderboard - and finds more real bugs
• How we would have caught a $100M+ defect that frontier models missed