Green GitHub Pull Request Fails in Merge Queue: Why?

When a pull request shows a green checkmark but still fails in the merge queue, the cause is almost always a change in context: the merge queue tests your PR combined with the latest base branch and other queued PRs, not in isolation. This can surface merge conflicts, flaky tests, or dependency issues that didn’t exist when your PR was last checked.

Formula

The merge queue doesn’t use a single formula, but the core logic is simple: mergeable = (your PR changes) + (latest base branch) + (all other queued PRs) all pass CI together. In contrast, a standalone green check means your PR changes + base branch at the time of the last push passed CI.

Key variables:

• PR changes – the commits you’ve pushed to your feature branch.
• Base branch – the branch you’re merging into (e.g., main), which may have advanced since your last CI run.
• Other queued PRs – any PRs already in the queue that will be merged before or alongside yours.
• CI checks – the automated tests, builds, and linting that must pass.

Worked Example

Imagine your PR is based on main at commit A. Your PR adds a file config.json and CI passes. Meanwhile, someone else merges a PR to main that also modifies config.json. Now the queue tries to merge your PR into the new main (commit B). The queue creates a temporary merge of your PR + commit B + any other queued PRs. If that combined merge has a conflict or fails a test, your PR fails in the queue even though your original CI run was green.

In concrete numbers: your PR’s CI passed at 10:00 AM. At 10:05 AM, another PR changes the same line. At 10:10 AM, the queue attempts to merge both. The combined result is a merge conflict. The queue marks your PR as failed, and you must update your branch and re-run CI.

What the Merge Queue Actually Does

A merge queue (like GitHub’s built-in one) is a safety net for high-traffic repositories. Instead of merging PRs directly to the base branch, it holds them in a queue. For each PR, it creates a temporary branch that combines:

• The base branch’s latest commit.
• All PRs ahead of yours in the queue.
• Your PR’s changes.

Then it runs CI on that combined branch. Only if all checks pass does it merge. This prevents the classic problem where two PRs each pass individually but break when merged together.

The green checkmark on your PR only reflects the state of your branch at the time of your last push. It does not guarantee that your PR will pass when combined with newer changes.

Why a Green PR Fails in the Queue

Here are the most common reasons, with examples:

• Merge conflict with the base branch – Another PR changed the same file or lines. Even if GitHub’s UI doesn’t show a conflict yet, the queue’s temporary merge can hit one. Example: Your PR edits line 10 of README.md; another PR edits line 12; both merge cleanly individually, but the combined diff has overlapping context that Git can’t auto-resolve.
• Flaky tests – Tests that sometimes pass and sometimes fail due to timing, network, or randomness. Your PR passed CI once, but the queue’s run hit a flaky failure. Example: A test that checks the current time or makes an external API call.
• Dependency conflicts – Your PR adds a package version that conflicts with a dependency added by another queued PR. Example: Your PR requires lodash@4, another PR requires lodash@3.
• Environment differences – The merge queue may run on a different runner, with different cached dependencies, or with a different operating system than your PR’s CI. Example: Your PR’s CI used a cached node_modules, but the queue’s runner does a clean install.
• Required checks changed – A repository admin added a new required check (e.g., a security scan) after your PR was created. Your PR never ran that check, so it fails in the queue.
• Stale approval or status – If your PR requires review approval, and a new commit is added to the base branch, the approval may be invalidated. The queue then requires re-review, which hasn’t happened.

How to Diagnose and Fix a Queue Failure

When your PR fails in the queue, don’t panic. Follow these steps:

1. Click on the failed check in the merge queue section. Read the logs carefully – they show the exact command and error.
2. Look for merge conflicts – if the log shows git merge failed, you need to update your branch. Run git fetch origin main and git merge origin/main locally, resolve conflicts, push.
3. Check if another PR is the culprit – if the conflict is with a queued PR, you may need to coordinate with that PR’s author. The queue will automatically re-run once the other PR is merged or removed.
4. Re-run the failed checks – if the failure looks flaky (e.g., a timeout or network error), click “Re-run jobs” on the check. If it passes on re-run, it was likely flaky.
5. Update your branch – even if there’s no conflict, merge the latest base branch into your PR. This ensures your PR is tested against the most recent code.
6. Check for new required checks – go to the repository’s branch protection settings to see if any new checks were added. If so, you may need to push a trivial commit (like an empty commit) to trigger them.

If none of these work, the most reliable fix is to close and reopen the PR or push an empty commit (git commit --allow-empty -m "trigger CI"). This forces a fresh evaluation against the current base branch.

Preventing Queue Failures

You can reduce the chance of a green PR failing in the queue:

• Keep your branch up to date – regularly merge the base branch into your PR, especially before adding it to the queue.
• Keep PRs small and focused – smaller PRs are less likely to conflict with others.
• Use semantic merge queues – some tools (like Mergify or GitHub’s built-in) allow grouping PRs that touch different files, reducing conflict risk.
• Make tests deterministic – avoid time-dependent or network-dependent tests. Use mocks and fixed seeds.
• Pin dependencies – use exact versions in your package manifest to avoid unexpected updates.
• Monitor the queue – if you’re a maintainer, watch for patterns: if many PRs fail at the same time, it’s likely a base branch issue, not individual PRs.

Common Misconceptions

Misconception: “Green means it will merge.” Not true. Green only means your PR passed CI at that moment. The merge queue tests a different combination of code.

Misconception: “The queue is broken.” Usually it’s working as intended – it caught a real problem that would have broken the main branch. The queue is stricter by design.

Misconception: “I can just re-run and it will pass.” Sometimes, but if the failure is a genuine conflict, re-running won’t help. You must update your branch.

Frequently Asked Questions

Why does my PR show a green check but the merge queue says “Expected — Waiting”?

This means your PR’s individual CI passed, but the queue hasn’t run its combined checks yet. It’s waiting for other PRs ahead of you to finish. This is normal and not a failure – just wait.

Can I bypass the merge queue if my PR is green?

Only if you have admin rights and branch protection allows it. But bypassing the queue defeats its purpose – it exists to prevent broken merges. If you bypass, you risk breaking the main branch.

Why does the queue fail on a PR that has no merge conflict?

It’s not always about conflicts. The queue may fail because of a test failure that only appears when your code is combined with other changes. For example, your PR adds a function, and another PR calls it with different arguments – individually both pass, but together they fail.

What does “Queue build failed” mean exactly?

It means the temporary merge branch created by the queue failed at least one required check. The logs will show which check failed and why. Click on the failure to see the error message.

How do I remove my PR from the queue?

You can click “Remove from queue” on the PR page, or close the PR. If you need to make changes, remove it, update your branch, push, and re-add it.

Does the merge queue run all checks or just required ones?

It runs all checks that are marked as required in branch protection. Optional checks are not run. If a check is required, it must pass for the queue to merge.

When to Use a Merge Queue vs. Direct Merge

Merge queues are valuable for repositories with high commit volume or many contributors. They add a small delay (usually a few minutes) but prevent broken main branches. For small projects or solo work, direct merge is fine. For teams, the queue is worth the extra time.

If you’re frequently hitting queue failures, it’s a sign that your test suite is flaky or your PRs are too large. Fix those root causes and the queue will become a smooth experience.

Related

• Stop Social Media Data Being Used for AI
• Best Examples of AI Chatbots for Different Needs
• Google Fiber Plan Changes: What Subscribers Should Know

in t | Finish time | min | 50 | 0
in d | Distance | km | 10 | 0 | 100000
out pace | Average pace | min/km | t / d | 2
out speed | Average speed | km/h | d / (t / 60) | 2