GitHub merge-queue checks stay missing when CircleCI's shallow checkout looks up refs/heads/gh-readonly-queue/... after GitHub has already replaced that temporary branch. The pipeline does start. Checkout exits 128 with fatal: couldn't find remote ref, the jobs that depend on checkout stay not run, and CircleCI never creates the GitHub checks the queue is waiting for.
Confirm it in the checkout step log. A shallow checkout clones the repository first, then fetches the queue branch by name:
git clone --no-tags --depth 1 [email protected]:ORG/REPO.git . git fetch --no-tags --depth 10 --force origin +refs/heads/gh-readonly-queue/BASE/pr-N-SHA:refs/remotes/origin/gh-readonly-queue/BASE/pr-N-SHA fatal: couldn't find remote ref refs/heads/gh-readonly-queue/BASE/pr-N-SHA
The same project still checks out feature branches. The failure is limited to gh-readonly-queue/*.
GitHub creates those branches to test the queue and replaces them as the queue regroups. Shallow checkout spends its first commands cloning the default branch, then asks for refs/heads/$CIRCLE_BRANCH. On a busy queue that name is often already gone. Jobs that need the checkout are left not run. CircleCI reports a GitHub check for a job that actually starts, so the required check names never show up and the queue waits until its status-check timeout.
Fetch the commit instead of the branch name
In the checkout job, for branches matching gh-readonly-queue/*, fetch $CIRCLE_SHA1 before cloning the default branch. Use this in place of the shallow checkout step:
git init git remote add origin "$CIRCLE_REPOSITORY_URL" git fetch --depth 1 origin "$CIRCLE_SHA1" git checkout --force "$CIRCLE_SHA1"
$CIRCLE_REPOSITORY_URL is the SSH or HTTPS URL CircleCI already set for the project. If git fetch of the SHA fails with the same missing-ref error, that pipeline is for a tip GitHub has already replaced. Remove the pull request from the merge queue and add it again so GitHub creates a fresh branch, then confirm the new pipeline checks out.
Related pages
These are different failures:
Pipelines on
gh-readonly-queue/*never start, and Only build pull requests is on: How to allowlist additional branches for Only Build Pull Requests. Addgh-readonly-queue.*there.The merge-queue pipeline is blocked because the trigger is
github-merge-queue[bot]and Prevent unregistered users from triggering builds is on: GitHub Merge Queue Compatibility with CircleCI.The setup workflow reports success before the continuation workflow exists, and the queue merges or times out: Merge Queues: Preventing Early Merges Before Triggering Build. Raise GitHub's status check timeout so the queue keeps waiting for the continuation checks.
A required check never appears because a dynamic-config or path-filtering job never runs, including when checkout fails and later jobs are not run: Using the path-filtering orb blocks pull requests being merged on a protected branch.
The log says
fatal: reference is not a tree. That is a different checkout error: Understanding the "fatal: reference is not a tree" error.
GitHub describes the temporary branches in Managing a merge queue.