Prioritising urgent changes in a merge queue

A merge queue is built for steady throughput: entries batch together, each batch is tested on top of the ones ahead, and nothing lands untested. During an incident that design works against you. The fix is approved, but there are eleven entries ahead of it, each batch takes nine minutes, and production is down. The temptation is to bypass the queue — merge directly, skip checks — which is how incident fixes end up breaking main a second time. Queues offer better options: moving an entry to the front, testing it alone rather than in a batch, and as a last resort a documented bypass with consequences everyone understands. This page sets those up before you need them, within merge queues and required checks.

When to use this approach

  • Your default branch uses a merge queue or merge train, and incidents sometimes need fixes landed quickly.
  • An urgent fix once waited behind a long queue, or someone bypassed the queue and broke main.
  • You want a predictable, rehearsed path for urgent changes rather than improvisation.
  • The queue is already set up, as in setting up a GitHub merge queue.

Step 1 — Use jump-to-front first

Most queues let a maintainer place an entry at the head. The entry is still tested — on top of the current main, without the entries it skipped — so the guarantee holds; only the order changes.

# GitHub: add a PR to the front of the merge queue (GraphQL)
gh api graphql -f query='
  mutation($pr: ID!) { enqueuePullRequest(input: {pullRequestId: $pr, jump: true}) {
    mergeQueueEntry { position } } }' \
  -f pr="$(gh pr view 951 --json id --jq .id)"
# GitLab: "merge immediately" restarts the train; prefer adding to the train first if time allows
glab mr merge 951 --auto-merge
Options for an urgent fix, by what they preserveWaiting in line preserves everything but may take too long. Jumping to the front keeps full testing and only changes order. Testing the fix alone keeps testing and avoids a batch's failure risk. Bypassing the queue skips testing on the final state and should be reserved for emergencies.Tested before landing?Time to landwait in lineyesqueue length × runjump to frontyesone runjump + solo batchyesone run, no batch riskbypass queueno (stale)minutesjump-to-front solves almost every urgent case without giving anything up

Jumping invalidates the batches already running, which restart behind the urgent entry. That cost is acceptable for an incident; it is why jumping should be reserved for incidents.

Step 2 — Keep the urgent entry out of a batch

If the urgent entry is batched with others and one of them fails, the urgent fix is delayed by bisection. Configure the queue so an entry at the head can be tested alone, or set a minimum group size of one and let the queue form a batch only when entries accumulate.

# Repository ruleset (merge queue parameters, GitHub) — illustrative values
merge_queue:
  grouping_strategy: ALLGREEN
  min_entries_to_merge: 1          # never wait for others to form a batch
  max_entries_to_build: 5
  min_entries_to_merge_wait_minutes: 2

With min_entries_to_merge at one, a jumped entry starts testing immediately rather than waiting for the accumulation window.

Step 3 — Make the fix itself small

The fastest pipeline is the one with least to do. An incident fix should be the smallest change that restores service — often a revert — not a refactor. A revert of a recent merge is easy to review and almost always passes CI.

git switch -c incident/revert-search-index main
git revert -m 1 5a9e3c1 --no-edit
git push -u origin HEAD && gh pr create --title "Revert #812: index rebuild locks orders table (INC-4471)" --fill

Reverting merges correctly is covered in undoing a bad merge on a shared branch.

An incident fix through the queueThe incident starts and a revert is prepared within minutes. Review is a quick approval because the change is small. The fix jumps to the front of the queue and is tested alone on current main. It lands about ten minutes after review, with the queue's guarantee intact.Incidentorders table locked10:41Revert PRsmall, obvious10:49Approvedone reviewer10:52Jump to fronttested solo10:53Landedmain still green11:02twenty minutes end to end, and nothing untested reached main

Step 4 — Document a break-glass bypass for when the queue itself is broken

Sometimes the queue cannot help: CI is down, the queue is stuck, or the required checks themselves are the problem. For that case, define a bypass in advance: who may use it, how, and what follows. A ruleset bypass list containing only an incident team, with bypass through pull request only, leaves a reviewed record.

Break-glass merge (documented in the incident runbook)
  Who:    members of @acme/incident-commanders only
  When:   CI or the merge queue is unavailable AND production impact is ongoing
  How:    merge the reviewed PR with the ruleset bypass ("merge without waiting for requirements")
  After:  run the full pipeline on main immediately; post the run link in the incident channel

Temporary elevation for the incident team is covered in granting temporary elevated access with expiry.

⚠️ SAFETY WARNING: A bypass merge lands a commit that was not tested on top of the current main. If another change landed in the meantime, the combination is untested and may break main. Immediately after any bypass, run the full pipeline on main and be ready to revert. Every bypass should appear in the incident review.

Choosing the urgent pathIf the queue and CI are healthy, jump the fix to the front and let it be tested alone. If CI is healthy but the queue is stuck, fix or restart the queue first. If CI itself is down while production is affected, use the documented break-glass bypass and run the full pipeline on main afterwards.What state is CI and the queue in?both healthyJump to fronttested soloqueue stuckUnstick the queuethen jumpCI down + outageBreak glassfull run on main afterthe bypass is the last branch for a reason — it is the only one that lands untested code

Step 5 — Rehearse and review

An urgent path that nobody has tried fails under pressure. Rehearse it during a calm week — jump a trivial pull request, time it — and include queue behaviour in incident reviews.

# How often was the queue jumped or bypassed last quarter, and why?
gh api "repos/$OWNER/$REPO/rulesets/rule-suites?time_period=quarter&rule_suite_result=bypass" \
  --jq '.[] | "\(.pushed_at[:10]) \(.actor_name) \(.ref)"'

Validation checklist

Frequently Asked Questions

Does jumping to the front skip any checks?

No. The entry is tested with all required checks on top of the current main. It skips waiting, not testing.

What if two urgent fixes arrive at once?

Jump both; they form the head of the queue in order and are tested together or in sequence according to the queue’s grouping. If either fails, the other proceeds after bisection.

Should hotfix branches bypass the queue entirely?

If they target main, no — they should take the fast path through it. Fixes targeting a release branch go through that branch’s own process, as in hotfix branches that do not drift from main.