GitHub PR Checks Pass, But Merges Blocked? Understanding the Hidden CI/CD Discrepancy
The GitHub Conundrum: When Checks Pass, But Merges Don't
Imagine this scenario: you've pushed a change to your feature branch, your GitHub Actions workflow runs, and gh pr checks --required confidently reports "PASS." All green! You're ready to merge, but then, GitHub's UI or GraphQL's mergeStateStatus insists your Pull Request (PR) is "BLOCKED." Frustrating, right? This isn't a rare glitch; it's a specific interaction within GitHub's branch protection rules and CI/CD check evaluations, particularly when dealing with concurrent workflow runs on the same head SHA.
Unpacking the Discrepancy: Display vs. Merge Gate
The core of the problem lies in how GitHub evaluates required checks for display versus for actual mergeability. As detailed in a recent community discussion, the required-check projection (what gh pr checks shows) often reads the "best completed check runs" for a given head SHA. This means if one of your concurrent workflow runs completes successfully, that's what gets reported as PASS.
However, the merge gate—the actual mechanism that determines if a PR can be merged—reads the "check suite's aggregated conclusion." This aggregation can still count a failed or cancelled run, even if a sibling run on the exact same head SHA was successful. This often occurs when workflows are configured with concurrency groups and cancel-in-progress: true, leading to overlapping pull_request events (e.g., opened followed quickly by labeled or synchronize) where an earlier run is cancelled, leaving its failed status to linger in the merge gate's evaluation.
This subtle but significant difference can lead to a state where your developers see green, but your CI/CD pipeline remains stalled, directly impacting your team's velocity and the reliability of your software project tracking tool metrics.
The Data-Driven Investigation: DankerMu's Reproductions
Community member DankerMu meticulously documented several instances and even performed controlled experiments to reproduce this exact state. Through PRs #477, #496, and #506, they observed the discrepancy. Their dedicated PR508 experiment provided conclusive evidence: a successful gh pr checks output alongside a BLOCKED mergeStateStatus. This was consistently tied to a newer, failed, or cancelled check suite coexisting with an older, successful one on the identical head SHA.
Subsequent observations on PRs #562 and #568 further solidified the findings. In each case, a required check query reported PASS from one successful run, while the mergeStateStatus was BLOCKED because another, cancelled run (often triggered by a different pull_request event like labeled) still held a failed aggregate conclusion. Crucially, these issues occurred without any changes to the PR's head commit, branch protection rules, or workflow configuration.
Proven Recovery Strategies for Unblocked Merges
The community discussion, particularly the insights from kittimzhe, highlighted two primary levers to resolve this "unchanged-head" blocked state without resorting to an admin bypass or adding an empty commit:
- Close and Reopen the PR: This is often the "natural" resolution observed in some cases. Reopening a PR fires a
pull_requestevent with thereopenedaction. If your required-check workflows listen to this event (which is default unless explicitly narrowed), they will re-run, leading to a fresh check suite aggregation that can resolve the blocked state. - Re-run the Cancelled/Failed Suite: The most direct and auditable recovery method. By specifically re-running all jobs of the *affected cancelled or failed suite* (not just the green one), you force a re-evaluation of that suite's conclusion. DankerMu's experiments consistently showed that this action, using commands like
gh run rerun, led to a CLEANmergeStateStatusand successful ordinary merges.
While adding a new commit to the head (e.g., via the "update branch" button) will also trigger new checks and resolve the issue, it's often an undesirable workaround as it pollutes the commit history and isn't a targeted fix for the underlying discrepancy.
Impact on Productivity and Project Delivery
This GitHub conundrum has direct implications for engineering teams and their leadership. When developers encounter a "green but blocked" PR, it introduces friction, delays, and frustration. It can skew your software project tracking tool metrics, artificially inflating cycle times and lead times, making it harder to accurately assess team performance and delivery predictability.
For product and project managers, these unexpected blocks can derail release schedules and create uncertainty. For CTOs and engineering leaders, it highlights the importance of deeply understanding the nuances of your core software engineering tool set. Relying solely on surface-level indicators like a green checkmark can mask underlying inefficiencies and lead to manual interventions that erode automation benefits.
Elevating Your CI/CD Tooling and Leadership
To mitigate this issue and enhance your team's productivity, consider the following:
- Educate Your Team: Ensure developers, product managers, and delivery managers understand this specific GitHub behavior and the proven recovery steps. Knowledge empowers teams to self-diagnose and resolve issues quickly.
- Monitor Beyond the Surface: Encourage checking
mergeStateStatusdirectly via GraphQL orgh pr view --json mergeStateStatus, especially when a PR appears blocked despite passing checks. - Review Workflow Configurations: Analyze your GitHub Actions workflow
concurrencygroups andpull_requesteventtypes. Whilecancel-in-progress: trueis often desired, understanding its interaction with multiple events on the same head is key. - Automate Diagnostics: Consider adding custom checks or bots that monitor for this specific "PASS but BLOCKED" state and provide guidance or even trigger the appropriate rerun action.
Mastering the intricacies of a powerful software engineering tool like GitHub Actions is crucial. Sometimes, the most effective insights come from a deep dive into how your existing tools function, rather than seeking external solutions. Understanding these internal mechanisms can be a powerful, almost Sourcelevel free alternative for gaining deeper visibility into your development pipeline's health.
Conclusion: Mastering Your Development Workflow
The "checks pass, but merges block" scenario is a testament to the complexity of modern CI/CD systems. While GitHub provides robust automation, understanding its nuanced behaviors is paramount for efficient and predictable software delivery. By recognizing the discrepancy between check projection and merge gate evaluation, and by implementing the proven recovery strategies, engineering teams can unblock their PRs, maintain velocity, and ensure their software project tracking tool reflects true progress. Empower your team with this knowledge, and you'll transform a frustrating roadblock into an opportunity to deepen your mastery of your development workflow.
