Auto merge toggleable feature

[danmt]

What's the itch?

All PRs in needs_human are basically auto-merged unless they are a release PR. it would be great to have a way for consumers of ceremony to choose whether they want to automatically merge PRs

What would "done" feel like?

I think an ALLOW_AUTO_MERGE or something that you can set at the consumer site that would make it so PRs that get to needs_human are automatically merged. We might want to have an AUTO_MERGE_RELEASE just in case. both are closed by default (false). also we probably want to define somewhere the logins that are allowed to create PRs that actually get there.

[dan-claude-bot]

🧹 Correction by triage, 2026-08-17T01:03Z, and the error is triage's own. Two present-tense board claims below were false at the moment this comment was published, not aged by it — I measured the queue earlier in the pass and carried the reading forward into the write. Both are struck in place. Nothing in Options, Recommend, Default or the Analysis changes, and the ask is unchanged. Re-measured just now from the label timelines rather than the threads:

• .github/labels.conf — the two builder logins join the fleet roster: two behaviour-neutral panel[<login>]= rows, so a builder-set rerun-owed clears gate 1 #452 and actions/ci-rerun — fleet_roster prints the roster with duplicates, and the gate-1 refusal comment is where a human reads it #453 were already claimed when this was written. @andriujoseba took .github/labels.conf — the two builder logins join the fleet roster: two behaviour-neutral panel[<login>]= rows, so a builder-set rerun-owed clears gate 1 #452 at 2026-08-16T22:06:32Z and @cndgrr took actions/ci-rerun — fleet_roster prints the roster with duplicates, and the gate-1 refusal comment is where a human reads it #453 at 22:16:33Z — eleven minutes and sixty-one seconds before this comment. The ready set at that instant was empty, not two.
• Both have since merged and closed — #454 at 2026-08-17T00:46:21Z and #455 at 00:46:36Z, both by you. So the two issues this comment called unclaimed backlog were in fact approved, green and sitting at state:needs-human waiting on the hand press this discussion is about. That strengthens your premise rather than weakening it, which is why the correction is worth the edit.
• The board at this write: #456 claimed by @cndgrr at 00:51:04Z carrying draft PR #457; #423 post-merge on its own unrelated wake; the ready set empty, and no other pull request open.

Re-verified rather than assumed, and unchanged: Stops — nothing still holds — nothing on any of the three boards is held by this decision. No open issue in ceremony, crew or incubator carries needs-ruling, all three read live at this write. The default is still none — hard block, which does not age, so no rung falls and I take no pick.

Two clauses I am deliberately not striking, so their status is on the record rather than left to a reader: "your #435 ruling today put both builder logins in it" was false when written — main's .github/labels.conf carried no panel[<login>]= row until 00:46:21Z — and is true now, so today's reader reads it correctly. And "26 times in this repository today" counts 2026-08-16; two more hand merges landed at 00:46Z on the 17th, both of them exactly the shape the toggle would have taken.

🧭 needs-ruling — Auto-merge needs a token that may merge, and this fleet has deliberately never had one. Which side holds it: GitHub's own auto-merge behind branch protection, or a ceremony-owned merge step inside the reconciler?
Options: A — GitHub-native auto-merge. The reconciler arms it when it confirms state:needs-human; GitHub performs the merge. Requires allow_auto_merge and a branch-protection rule or ruleset carrying at least one required check on every adopting repo — none of the three has one today. B — a ceremony-owned merge step. The reconciler merges, in the same pass that concludes state:needs-human, behind a per-consumer workflow input defaulting to false. C — decline the toggle; the operator keeps the merge.
Recommend: B, on three measured grounds: it crosses no trust boundary release.yml has not already crossed (contents: write, git push origin main, :315); it needs no admin act and no plan change, so it works on incubator today where A may not; and A strands the post-release bump PR, turning "auto-merge everything but releases" into one new manual merge per release — worse than today on the flow you care most about.
Blocked: Stops — nothing. #452 and #453 are ready, unclaimed and untouched by this [struck — see the correction at the top: both were already claimed when this was written, and have since merged. Stops — nothing is unaffected]; #423 is post-merge on an unrelated wake. No issue on any of the three boards declares this thread, and none carries needs-ruling. Continues — you merge by hand, which is the measured status quo below and costs a median 5½ minutes of presence per PR, 26 times in this repository today.
Default: none — hard block, and structurally rather than by caution. Granting any token the right to merge is org policy, and A cannot fire by default because it requires an act only you can perform. A hard block does not age: no elapsed time and no re-measure makes it fire, and I take no pick at the 24-hour rung.

Analysis

Your premise is right, and it measures better than you stated it. Across the last 30 pull requests here: 29 merged, one closed, and of the 29, 26 reached state:needs-human and all 26 merged. Not one left the label for any other reason. Median state:needs-human → merge is 5½ minutes; 20 of the 26 land inside 20 minutes. The label is an excellent predictor of the destination.

What it is not is a trustworthy predictor of the moment — and that is the whole of the design question, so it is measured rather than argued. I walked every state:needs-human labeled/unlabeled event on the last 80 pull requests in each of the three repositories: 353 episodes, of which 167 were taken back again across 13 distinct pull requests.

Five of those pull requests account for 154 assertions and 152 take-backs, and the shape is identical on all five, in all three repositories, from both builder logins:

pull request	asserted state:needs-human	removed by the reconciler	eventually merged
incubator#133	80× (andriujoseba)	79× (github-actions[bot])	2026-08-12T08:15:45Z
ceremony#368	35× (cndgrr)	35×	2026-08-10T20:11:22Z
incubator#168	29× (andriujoseba)	28×	2026-08-13T20:11:02Z
crew#362	7× (andriujoseba)	7×	2026-08-05T14:11:10Z
incubator#94	3× (andriujoseba)	3×	2026-08-11T09:23:43Z

An agent writes the label on its duty tick; the reconciler removes it forty seconds later; five minutes on, the agent writes it again. This is not a bug — LABELS.md:32-34 specifies it: "The author sets it at handoff (the one hand-set state); the labeled event fires the sweep that validates the write within seconds." The labeled event is the unvalidated moment, by construction.

The case that decides where the hook goes

incubator#133, whole timeline:

• 00:48:56–00:52:47Z — the panel approves 90be98ca, which is the head that eventually merges.
• 00:55:53Z — blocker:ci-red goes up. The approved head is red.
• 00:55:22Z → 08:10:04Z — the builder asserts state:needs-human 80 times. decide_state refuses the first 79, correctly: a standing blocker disqualifies the label (labels-reconcile.sh:577).
• 08:11:02Z — blocker:ci-red clears, after 7 h 15 m, and the 80th assertion is left standing.
• 08:15:45Z — you merge.

Read that against the two hooks:

• On the labeled event, auto-merge ships a red head at 00:55:53Z — seven and a quarter hours early, on a PR the machine was about to reject and did reject eighty consecutive times.
• On the reconciler's confirmed verdict, auto-merge merges at ~08:12Z — three minutes before you did, and correct.

The review axis says the same thing. On crew#434, all three reviewers filed CHANGES_REQUESTED at eecb18e9 (06:51:29, 06:54:14, 06:56:43Z); the builder pushed f6d902cd at 06:57:45Z and hand-set state:needs-human 33 seconds later, on a head carrying zero verdicts. The reconciler took it back at 07:06:17Z. Fresh approvals arrived 07:18–07:34Z; it merged at 08:03:16Z. An event-hooked auto-merge merges a head three reviewers had just rejected.

So the hook is not a matter of taste, and it is the same under A and B: the trigger must be decide_state's own conclusion, never the label event. That function already carries five accumulated disqualifiers — draft, any blocker, a red head, needs-ruling, blocked (:567–:620), the last of them bought by #122, where a frozen PR reached state:needs-human and "told the maintainer to merge it". This is the reassuring half of the answer: acting on that verdict asks for no new race logic. Every race I could find in the record, decide_state already gets right. What changes is only who is allowed to act on it.

What each option costs

A — GitHub holds the credential. Its appeal is real: no ceremony workflow gains contents: write, and GitHub re-evaluates mergeability and required reviews at merge time. Its costs:

• The precondition does not exist anywhere. ceremony and crew return [] rulesets and 404 on branch protection; incubator returns 403 Upgrade to GitHub Pro or make this repository public. So A is an admin act per repository and possibly a paid-plan question on incubator. I could not read allow_auto_merge at all — it returns null at triage permission, which means not visible to me, not disabled.
• It strands the release bump. release.yml:315 pushes the -dev re-arm straight to main, with an explicit fallback: "direct push refused (branch protection?) — opening the bump PR instead", opening it --label release. Under A that fallback becomes the normal path, and since release PRs are excluded from auto-merge (below), every release would leave a bump PR waiting for you. Net: you stop merging ordinary PRs and start merging one bump PR per cut.
• One honest caveat: I am relying on GitHub's documented rule that auto-merge can only be armed on a PR blocked by a protection requirement. I hold no admin here and enabling it is your act, so I could not test it. If A is chosen, verifying that is task one of the issue, not an assumption inside it.

B — ceremony holds it. A repo-owned script a test can drive, which is also exactly what #171's standing fleet rule requires of any job whose token is write-capable — it names contents: write explicitly. The honest cost, stated plainly: a pull_request_target workflow gains the right to merge, in repositories with no branch protection. What makes that smaller than it sounds is that FLEET.md:30's invariant is about identities — "the agents team holds the triage role, not write" — and every fleet identity's rights stay {"admin": false, "maintain": false, "push": false, "pull": true, "triage": true} under B. A workflow token already writes to main here every release. B widens what that class of token may do; it does not create the class.

C — decline. Costs nothing and changes no doctrine. Against it: the itch is measured, not felt — 26 merges in this repository today, each needing you present.

Three things I settled from the repo, so they are not in the question

• Where the toggle lives. Not .github/labels.conf: its parser routes any unrecognised KEY=value line to parse_label_row, so ALLOW_AUTO_MERGE=true there is a parse failure that reds the reconcile job on every event until removed — the triage-actors= precedent, and it would land only with a pin bump per consumer. The reusable workflows already take with: inputs (runner, sweep_workflow, pr_workflow_name), so the toggle is an input with default: false. That is your "closed by default" requirement met exactly, opt-in per consumer, with no schema change and no pin bump for anyone who does not set it.
• AUTO_MERGE_RELEASE is in none of the three options. "A release is a PR, and merging it ships it" (README), and LABELS.md makes published artifacts a hard block by construction. So whichever option you take, the first deliverable excludes PRs carrying the release label, and I am not holding a second ask in reserve over it: if you want the release toggle in scope, say so in your reply and it is in scope. Left unsaid, it is out.
• The author allowlist you asked for already exists. load_fleet reads panel=, panel[<login>]= and triage-actors=, and your #435 ruling today put both builder logins in it. Reusing it costs nothing. A new field is a schema change with the parse-failure precedent above. The cost of reuse is the one The fleet roster names three review bots and triage — and neither identity that opens every PR. Who is in it, now that the roster also spends `actions: write`? #435 already named — one field carrying two facts becomes one field carrying three — and #453 is open precisely because the second fact already made the roster print unreadable. I recommend reuse and would write that cost into the issue rather than spend a new setting on it.

What lands whichever way you rule

Six sentences say a human merges: AGENTS.md:41, REVIEWER.md:124, LABELS.md:23, CONTRIBUTING.md:30, FLEET.md:30 and docs/CONSUMERS.md:260. Three of those files are in docs/VENDORED.txt, so the edit is mirrored byte-identically into every governed repo and reaches each one only at its own pin bump. AGENTS.md's is the load-bearing one — "Only humans merge. Convergence ends at state:needs-human, never at a merge button" — and under A or B it becomes "only humans and the consumer's own opted-in toggle". That is a real doctrine reversal and belongs in the same issue as the machinery, not after it. Sizing is an epic either way: the doctrine edit, the reusable-workflow input, the merge step and its tests are disjoint enough to split and too much for one PR.

Flag state

No needs-ruling label is set on any board, because nothing is blocked behind this — re-verified at this write against the label timelines rather than the threads: no open issue in ceremony, crew or incubator carries the flag, and this repository's only ready work is #452 and #453, neither of which this touches [struck — see the correction at the top: the ready set was empty at this write and is empty again now; the needs-ruling census in this sentence was correct and still is]. The decision is yours, @danmt; the hard-block default means it cannot be taken by anyone else, including me.

[danmt]

B @dan-claude-bot

[dan-claude-bot]

Ruled B, recorded as a decision, and minted — triage, 2026-08-17

The decision, in the form it now binds: a ceremony-owned merge step inside the reconciler, behind a per-consumer workflow input that is closed by default. A (GitHub-native auto-merge behind branch protection) and C (decline) are spent; no minted issue re-opens either. The hard-block default never fired and no rung was taken — you answered inside the first hour, and the pick is yours, not mine.

No flag to clear. No needs-ruling label was ever set on any board for this, because nothing was held behind it — re-verified at this write against the label timelines in ceremony, crew and incubator: no open issue in any of the three carries the flag, and the ready set here was empty when the ask was written and is not empty now for the reason below.

What was minted

An epic and four children, a single serial chain, because they all extend the same three files and the doctrine half must land last:

	issue	queue
epic	#458 — auto-merge as a consumer's own toggle	—
1	#459 — the toggle, plumbed and inert: one input, the fleet predicate, one pure verdict, no merge	ready, unclaimed
2	#460 — the merge itself: head-pinned, confirmation-read, through run()	blocked behind #459
3	#461 — the post-merge dispatch (see the disclosure below)	blocked behind #460
4	#462 — the doctrine: eight sites, plus the consumer guide	blocked behind #461 and #456

Three of your asks landed as written, and one is out by the rule the ask itself stated:

• The trigger is decide_state's own conclusion, in the pass that concludes it — never the labeled event, never the label. That is the whole of the design, and it is the incubator#133 measurement above, not taste.
• off is the default everywhere, and the input names the merge method (off | merge | squash | rebase) rather than being a boolean: a repository can have merge commits disabled, and a two-value toggle would be unusable there with no way to say so.
• The author allowlist is the fleet set you already maintain — panel=, every panel[<login>]= row and triage-actors= in .github/labels.conf. No new field, no schema change, no pin bump for anyone who does not opt in.
• AUTO_MERGE_RELEASE is out. The ask said "if you want the release toggle in scope, say so in your reply and it is in scope; left unsaid, it is out", and the reply said B. Nothing in the four issues forecloses it — one line here and I mint it.

One thing I owe you, measured after you ruled

A merge performed by the sweep raises a push that starts no workflow run. GitHub creates no runs from GITHUB_TOKEN-raised events (workflow_dispatch and repository_dispatch excepted) — the same rule release.yml:173-175 already states about its own bump push, and the rule the sweep's own wake depends on. So an auto-merged commit runs neither ci.yml's push: branches: [main] nor the release door. Release PRs are excluded, so the ship path is untouched and the door is a green no-op on everything else; what is genuinely lost is main's own CI, once per auto-merged PR.

I did not price that in the ask, and it is disclosed here rather than folded in quietly. It does not reverse B: the cost is shared by A, whose arming token is the same one; a write-capable PAT is org policy and was never granted; and GitHub's own exemption — a workflow_dispatch — is exactly the mechanism the trigger job already uses. #461 restores the signal that way, with an empty-by-default post_merge_workflow input. It is the one issue in the arc you did not ask for, and it is why the arc is four issues rather than three.

What stays yours

Adoption. The arc ships the capability closed everywhere, including here — self-labels-sweep.yml keeps contents: read and passes no input, and no child touches any caller. Turning it on in a repository is two lines in that repository's sweep caller (with: { auto_merge: merge } and contents: write), and it should follow the arc's release, not its first merge: until #461 lands, an opted-in repo would trade a hand press for a silent loss of main's CI.

#459 is deliberately safe to enable on its own — it decides and logs and merges nothing, so you can switch it on under contents: read, read a week of sweeps saying what they would have merged, and grant the permission only if the verdicts look right.

Two smaller facts, in the epic and in the guide rather than left for you to discover: auto-merge ignores merge-next (queue order is intent the reconciler must not guess — the loser of a real conflict is disqualified by blocker:conflict instead), and it can be slower than your hand — the labels caller has no pull_request_review trigger, so a final approval's only wake is the hourly cron, against your measured 5½-minute median press.

Closing this as resolved; the epic is the venue now, and the release-toggle line above is open whenever you want it.