skip to content

Why would every entry in a GitHub merge queue time out with no checks reported?

level: seniorimportance: should knowfreq 32%

answer

  1. the pull request is not what runs
  2. which ref did anything actually build
  3. waiting for a name nobody posts
  4. uniform failure means configuration
  5. the timeout is a valve, not a cause

basics

~20 s

Because nothing is producing results for the merge group. CI that only reacts to pull requests never runs on the temporary queue ref, so the checks required on the branch stay unreported until the check timeout evicts each entry.

solid answer

~50 s

This is the classic first-day merge-queue failure. The queue tests a **merge group**, not your pull request branch: GitHub creates a temporary `gh-readonly-queue/...` ref and emits the **`merge_group`** event, and the checks required on the target branch must report success for that ref. If your pipeline is wired only to pull-request activity, it never starts for the merge group, the required checks sit unreported, and after the configured check response timeout GitHub removes the entry — every entry, identically, which is the tell. The second cause is a **name mismatch**: the check reported for the merge group is not spelled exactly as the required check on the branch, so GitHub is still waiting for something that will never arrive. Diagnose it by opening the queue entry, looking for whether any run exists against the queue ref at all, and comparing the reported names with the required list; then fix the trigger or the name.

go deeper

for a junior

Recall that a queued pull request is validated on a separate temporary branch, so a green pull request does not by itself mean the queue has anything to look at.

for a middle

Explain that required checks must report against the merge group ref, and that a pipeline reacting only to pull requests produces no result there at all.

for a senior

Work the diagnosis in order — is there a run against the queue ref, do reported names match the required list exactly, is the timeout above p99 — and recognise uniform eviction as a configuration signature.

for a principal

Own the rollout: validate that merge-group checks report before enabling a queue on a busy repository, and standardise the required-check naming so the same trap does not recur across teams.

## The symptom Every entry enters the queue, sits in a building state with no results, and is eventually removed. Nothing merges, the pull requests themselves look perfectly green, and disabling the queue makes merges work again. Because the failure is uniform across every entry, it is a configuration problem, not a code problem — genuine breakage would evict some entries and let others through. ## Cause one: nothing runs for the merge group The queue does not test your branch. It builds a temporary ref containing the base plus the entries ahead plus yours, and announces it with the `merge_group` event. Required checks must report against **that ref**. A pipeline configured to react only to pull-request activity has no reason to start when a merge group appears, so no run exists, no check reports, and the entry waits for evidence that will never arrive. The fix is on the CI side — the pipeline must react to merge groups — and the platform side of it is simply that the checks required on the branch are the ones the merge group must satisfy. This is worth naming precisely in an interview, because it explains the shape of the failure: uniform, immediate on adoption, and invisible on the pull requests themselves. ## Cause two: the names do not match Required checks are matched by name, exactly. If the merge-group run reports `build (ubuntu)` while the branch requires `build`, GitHub sees the required check as still missing. This bites especially when a pipeline reports differently-named results depending on what triggered it, so the pull-request run satisfies the requirement and the merge-group run does not. Compare the reported names on the queue ref against the branch's required list character for character — including any parameter suffixes the runner appends — before assuming anything more exotic. Where required checks are pinned to a reporting App, a result posted by a different integration with the right name also fails to satisfy the requirement; that is rarer, but it produces the same silent wait. ## Cause three: the run cannot start Even with the right trigger, a run can fail to exist: the pipeline may be disabled for the repository, runners of the required kind may be unavailable, or organization policy may block the actions the workflow needs. In each case there is no result to report, so the queue behaves identically. Look for whether *any* run was created for the queue ref — the presence or absence of a run is what separates this class from the naming class. ## Why the timeout is the right behaviour A queue that waited forever would let one misconfiguration freeze all merges in the repository. The **check response timeout** bounds the wait: when it expires, the entry is removed exactly as a failing one would be, the temporary ref is cleaned up, and the queue moves on. It is a safety valve, not a diagnosis, so treat mass timeouts as a signal to look at what is (not) reporting rather than as a reason to raise the timeout. Raising it only makes the same failure take longer to surface — although a timeout set below your real p99 CI duration is a genuine separate bug, and worth ruling out first, since it produces the same eviction for slow-but-alive runs. ## A practical checklist 1. Does a run exist against the `gh-readonly-queue/...` ref for an evicted entry? No run means a trigger, permission or capacity problem. 2. If a run exists, do its reported check names match the branch's required checks exactly? 3. Is the check response timeout above your p99 CI duration? 4. Are the required checks pinned to a specific reporting App that is not the one posting? 5. Does the queue's merge method conflict with another branch rule, such as linear history? That produces a different failure — checks pass but nothing lands — and is worth distinguishing. ## Interview framing Name the mechanism first: the queue tests a temporary ref and required checks must report there. Then give the ordered diagnosis — is there a run at all, do the names match, is the timeout sane — and note the tell that makes this diagnosable in seconds: it hits every entry identically, which real code failures never do.

  • How do you tell a trigger problem from a naming problem in a few seconds?
    Look for whether any run exists against the gh-readonly-queue ref for an evicted entry. No run at all means the pipeline never started — a trigger, permission or capacity problem. A run that completed but left the required check unsatisfied means the reported name does not match the required one, or the result came from a different reporting App.
  • Why is raising the check response timeout the wrong first response to mass evictions?
    Because the timeout is a safety valve, not the cause. If nothing ever reports, a longer wait just delays the same eviction while blocking every merge for longer. The one exception worth ruling out first is a timeout set below your real p99 CI duration, which evicts slow-but-healthy runs and mimics the same symptom.
  • Checks pass on merge groups but nothing ever lands. What is different about that failure?
    That is not a reporting problem; the group was validated and then rejected at merge time. The usual cause is a conflict between the queue's configured merge method and another branch rule — a queue set to create merge commits on a branch that requires linear history, for example. Align the merge method with the branch's rules.

saying these in an interview costs you the question

  • Raises the check timeout instead of finding what never reported
  • Assumes pull-request runs automatically cover merge groups
  • Thinks the queue merges when checks are simply absent
  • Ignores exact check-name matching against the required list
  • Blames flaky tests for a failure that hits every entry alike

context

resolving links…