Merge overrides
How to land a pull request when the merge queue or required CI status check
is the wrong tool for a rare, time-sensitive change.
The organization owner for this mechanism is
burin-labs/.github. Read that README
section for the full contract. This page is the Harn-facing how-to.
Prerequisites#
- You are an organization owner/admin on
burin-labs, or a repository admin onburin-labs/harn. - The pull request head lives in
burin-labs/harn(not a fork). - You can fix forward on
mainif the land is wrong.
Labels#
bypass-ci: cancel competing runs for the head SHA and publish a successfulCI statuscheck. Does not merge.bypass-merge-queue: squash-merge immediately whenCI statusis already green. Skips the merge queue.force-merge: publish successfulCI status, then squash-merge immediately. Skips CI proof and the merge queue.
Labels are only a trigger. The reusable workflow re-checks that the actor is an
organization or repository admin and refuses fork pull requests. Privileged
merges use the harn-release-bot installation token, which is a ruleset bypass
actor.
When to use an override#
bypass-merge-queue and force-merge land outside the queue, which rebuilds
every queued merge group. The workflow allows them only when one of four
measured signals holds, and refuses the label otherwise:
- Main is red: an open
[CI] Main is redissue, or the newest conclusiveCIrun onmainfailed. The run is read from theCIworkflow's own history, so unrelated workflow runs cannot push it out of view. - The pull request is a release-train pull request: a repin, a version-only
bump, or one labeled
release-blocker. - The merge queue is wedged: the pull request has been queued for 90 minutes or
more and no merge group run is active on
main. - The automated reviewer is down: it posted its did-not-finish marker for the current head and nothing has approved that head since.
The reason text is never evidence; the signals are read at decision time. See
the org contract
for the exact rules. bypass-ci keeps the queue, so it is not gated by these
signals.
When not to use an override#
- A long or costly queue. Each bypass rebuilds every queued group; on 2026-10-23 green-PR bypasses cancelled most merge group runs. A pull request that must land first takes the queue's jump-to-front instead, which keeps the combined-tree check.
- Ordinary feature work, dependency bumps, or “CI is slow today.”
- Changes you cannot fix forward if they break
main. - Pull requests from forks.
Steps#
- Open or identify the same-repo pull request.
- Add exactly one override label.
- Read the audit comment posted by
Merge override dispatch. - For
force-mergeorbypass-merge-queue, confirm the PR merged. - Prefer removing the label after the land; the audit comment remains.
Organization admins can also use GitHub’s “Bypass rules and merge” UI for the
main protection ruleset, which grants OrganizationAdmin bypass in
pull_request mode. That bypass does not skip the merge queue. The
merge queue ruleset's only bypass actor is harn-release-bot, so an admin's
gh pr merge goes through the queue, and the labels above are the only way to
skip it.
The queue is also what keeps generated files correct. GitHub ignores the
-merge attribute in .gitattributes, so two pull requests that each
regenerate one output can merge into a file no generator produced. Only the
queue's generated-file check on the combined tree catches that before it
reaches main (#8817). A bypass-merge-queue land that touches generated
outputs should be rebased and regenerated on current main first.
Related#
- Org contract and wiring template:
burin-labs/.githubREADME - Harn agent notes:
AGENTS.md→ “Merge overrides”