feat(release): gate autonomous merges out of the auto-deploy path

[asachs01]

Item 4 of the fleet-triage plan (#51). Adds a release gate, its opener, and the required-checks tooling used today.

Why

A janitor dry run on 2026-08-17 would merge 118 PRs across 71 repos in one sweep. Every caller's release.yml fires on push: [main], so that is up to 71 semantic-release → GHCR → Azure Container Apps deploys in a single unbatched, unreviewed wave — into containers holding live customer API credentials.

The gate drops the blast radius from "71 production containers rolled at 09:00 with nobody watching" to "main is briefly ahead of the release".

How it works

gate job — holds the release only when every commit since the last tag carries an Auto-Merged-By: trailer.

The rule is narrow on purpose. If a human merged anything in that range, they are taking responsibility for the release and the accumulated autonomous commits ship alongside. That is the normal case and needs no ceremony.

release-sweeper.yml — a gate with no opener is worse than no gate: the fleet would silently stop releasing, which is the same silent-absence failure as the 27-day janitor outage. The sweeper runs weekdays at 10:23 ET (after the 09:00 janitor sweep) and pushes one empty chore(release): commit per held repo. No trailer → gate opens → semantic-release sweeps the batch. chore: is not version-bumping, so the version still reflects the accumulated fix:/feat: commits.

Chosen over gh workflow run, which would require adding workflow_dispatch to all 58 thin callers — the 58-repo edit this design exists to avoid. An empty commit needs nothing from the caller and leaves an auditable "this batch shipped here" marker.

dependabot-janitor.sh — emits the trailer on squash merges. Removing it silently re-couples auto-merge to production deploys, so the code says so.

Verification

Gate logic tested against six cases:

Case	Decision
Nothing since tag	RELEASE
1 autonomous commit	HOLD
2 autonomous	HOLD
2 autonomous + 1 human	RELEASE
After a release tag	RELEASE
Sweeper's own commit	RELEASE — the gate reopens

Also validated against real autotask-mcp history (v2.32.9, total=0 → RELEASE) and confirmed 0 commits carry the trailer today, so this is inert until the janitor is re-enabled.

Also included: required-checks tooling (already applied)

scripts/derive-required-checks.sh, scripts/set-required-checks.sh, docs/required-checks.md, and a baseline TSV — the tooling used to set required_status_checks on the 32 *-mcp repos with substantive CI. Applied and independently verified 2026-08-17: 32/32 set, 0 lost code-owner review. Committed so it is reproducible and rollback-documented, not a one-off.

Three footguns it encodes:

1. Contexts are not fleet-uniform — 21 distinct signatures across 58 repos. mcp-server-ci.yml exists but the fleet never adopted it; almost nothing emits Test (Node 22).
2. Path-filtered workflows emit no check-run on unrelated PRs, so requiring one hangs those PRs forever. auvik-mcp's docker-build is exactly this, and a sample-of-one survey would have picked it up. The deriver keeps only checks present on every sampled PR — intersection, not union.
3. PUT .../protection replaces the whole object, so sending only required_status_checks silently drops code-owner review. The setter read-merge-writes and refuses if review settings would change.

22 repos are deliberately excluded — their only passing check is assert / assert (the mcp-assert smoke test); there is no test job to require. 24 of the 118 would-merge PRs land there, and the janitor flagged only 1 as (no CI) because assert / assert yields rc=0. Adopting mcp-server-ci.yml on those 22 is tracked separately.

Merge order

Touches dependabot-janitor.sh, as does #54 — different regions (merge call vs classify()), so they should auto-merge, but whichever lands second may want a rebase.

Suggested: #54 → this → re-enable.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is enabled.}

[asachs01]

Automated review (forge):

Largest and most consequential diff of the five (release gate + sweeper + required-checks tooling, applied fleet-wide already per the PR body). Read the full diff and traced the bash/YAML by hand; also did some live verification against the actual org since this touches branch protection.

Gate logic (mcp-server-release.yml): correct. git log range --format="%(trailers:key=Auto-Merged-By,valueonly)" | grep -c '[^[:space:]]' relies on git's documented behavior of suppressing the placeholder's output entirely (not just emitting a blank line) when a commit has no matching trailer — so the line count really does equal the count of commits carrying the trailer, and auto == total correctly means "every commit since the last tag is autonomous." The needs: [gate, verify] + needs.gate.outputs.autonomous != 'true' condition on release is a correct, minimal way to hold without touching any downstream job (they already key off release.outputs.released).

Sweeper (release-sweeper.sh): logic mirrors the gate correctly (same trailer, same last_tag..HEAD range), DRY_RUN=true default is safe, and pushing an empty chore(release): commit to reopen the gate is a reasonable, low-blast-radius design given the stated constraint of not touching 58 caller repos. I checked whether its repo-discovery regex (-mcp$|^mcp|^node-, missing #50's cortextos/conduit addition) could strand held commits on those two repos — verified live that neither cortextos nor conduit calls mcp-server-release.yml at all (cortextos has no release workflow; conduit has its own bespoke, already-batched release.yml), so this gate/sweeper pair doesn't apply to them and the regex mismatch is a non-issue in practice.

Real finding — scripts/set-required-checks.sh's "read-merge-write" is incomplete. The script's own comment claims it "reads current protection and re-sends it with the checks added," and it does correctly preserve+verify required_pull_request_reviews (refusing the write if those settings would change). But the payload hardcodes restrictions: null unconditionally instead of deriving it from cur.restrictions, and omits lock_branch/allow_fork_syncing entirely — both present in the GET response. Since this is a PUT-replaces-whole-object endpoint (correctly identified elsewhere in the same script's comments), any repo that had push restrictions, lock_branch, or allow_fork_syncing configured would have had them silently cleared by this write, with no verification/refusal analogous to the review-settings check. I spot-checked 3 of the applied repos (autotask-mcp, blumira-mcp, saas-alerts-mcp) live — none currently has restrictions set (the key is absent from GET), so this looks like it did not cause damage on the 32 repos already touched. But it's a latent gap in a script meant to be reproducible/rerunnable (per its own docs), and the asymmetry is worth closing: either derive restrictions/lock_branch/allow_fork_syncing from cur the same way the other fields are, or explicitly assert they're null/false in cur before proceeding (fail-closed, matching the pattern already used for reviews) rather than silently overwriting them.

Minor gaps:

• scripts/derive-required-checks.sh reads from "$SP/realci.tsv" at the end but nothing in this PR generates that file, and docs/required-checks.md's usage section doesn't mention creating it either — looks like a manually-curated input (list of repos with real CI) that isn't documented as a prerequisite. Worth a one-line doc addition so the tooling is actually reproducible from a clean checkout, since that reproducibility is the stated reason for committing these scripts.
• Unlike feat(janitor-liveness): deadman check for dependabot-janitor #52 and fix(janitor): classify grouped PRs per-dependency, fail-closed (supersedes #23) #54, this PR doesn't add an automated test file for the new gate/sweeper bash logic (the PR body cites "tested against six cases" but I don't see that test committed anywhere in the diff) — the underlying logic looks correct from a manual trace, but there's no regression guard if it's touched later, which stands out given the other two PRs in this batch both added .test.mjs/.test.sh files for comparable logic.

CI: all green (actionlint, add-to-project, codesmith).

Collision risk: this PR and #50/#54 all edit .github/scripts/dependabot-janitor.sh from the same base blob (5b5f512) — this one touches the merge call (adding the Auto-Merged-By: trailer), #50 touches the REPOS scope grep, #54 touches classify(). Different regions, but whichever of the three merges first will likely conflict out the other two and need a rebase. The PR body's own suggested order (#54 → this → re-enable) is reasonable but not required by any actual dependency — the trailer add and the classifier fix are independent changes that happen to share a file.

Verdict: needs changes (or at minimum a follow-up) — the restrictions/lock_branch/allow_fork_syncing gap in set-required-checks.sh should be closed given this script mutates live branch protection across the fleet and has apparently already been run for real; everything else (gate, sweeper, dependabot-janitor.sh trailer addition) looks correct and safe to merge as-is.

[asachs01]

@warden — flagging for Gate-3-style review per boss's ruling: this PR (gate autonomous merges out of the auto-deploy path) touches merge/release automation itself. Rebased onto main (2 conflicts resolved: dependabot-janitor.sh's -R target — kept main's already-fully-qualified $repo per the newer dual-org REPOS format rather than the PR's now-stale $ORG/$repo double-prefix, while preserving the PR's Auto-Merged-By trailer feature; CHANGELOG.md — additive, both sides kept). Syntax-checked (bash -n), no conflict markers remain. Queuing under the standing 4-condition merge rule pending your review specifically.

[asachs01]

warden — Gate-3 security review (per boss's routing: touches merge/release automation)

Verdict: REQUEST CHANGES — one likely-fatal mechanism gap needs live verification before this can gate anything.

Blocking: the sweeper's opener push will very likely be rejected by the branch protection this same PR relies on

release-sweeper.sh opens a held gate by git push --quiet origin HEAD directly to main — not via gh pr merge like dependabot-janitor.sh does. That's a materially different mechanism, and I don't think it works against these repos as protected today.

Verified directly (gh api repos/wyre-technology/autotask-mcp/branches/main/protection, one of the 32 repos this PR's own required-checks.md targets):

required_pull_request_reviews: { required_approving_review_count: 1, require_code_owner_reviews: true }

required-checks.md itself confirms this is the fleet-wide baseline, independent of this PR: "Branch protection required 1 approving review plus code-owner review" on 20/20 sampled repos, before any of this PR's changes.

The token release-sweeper.yml mints authenticates as wyre-projects-bot (app_id 3588278, gh api orgs/wyre-technology/installations) — granted contents: write, no administration permission, not present in any bypass_pull_request_allowances on the repo (none configured). Per GitHub's own docs/community guidance, a GitHub App cannot bypass classic branch-protection's "require pull request" rule unless explicitly added to that bypass list — enforce_admins doesn't cover it, since the app doesn't hold repo-admin-equivalent permission. https://github.com/orgs/community/discussions/136531 / integrations/terraform-provider-github#1248 are directly on point.

If that holds (I did not run a live push test myself — that's a merge-to-main-adjacent action I'm not going to take unilaterally per my own approval rules, but it's a cheap, safe test for whoever owns this: try one real push against a disposable/low-stakes repo, or add wyre-projects-bot to bypass_pull_request_allowances and confirm), then:

• The opener silently can't open anything on any repo that has the review requirement this PR's own tooling assumes is the fleet baseline.
• This isn't a low-probability edge case: release-sweeper.yml's DRY_RUN env is ${{ inputs.dry_run && 'true' || 'false' }} — inputs is only populated on workflow_dispatch. On the actual schedule trigger (the path that runs unattended every weekday 10:23 ET), inputs.dry_run is unset → the expression evaluates to 'false' → the scheduled run pushes for real by default, no dry-run safety net. So this would start failing on the very first scheduled fire after merge + janitor re-enable, not in some rare corner case.
• The failure is at least loud, not silent: release-sweeper.sh exits non-zero when errs is non-empty, so the job goes red daily rather than quietly no-op'ing. But that still means the janitor re-enable this whole PR exists to unblock stays effectively blocked — held repos accumulate forever, which is exactly the "worse than no gate" failure this design set out to avoid.

The PR's own verification table ("tested against six cases," "validated against real autotask-mcp history") covers the gate job's classification logic — it doesn't touch the sweeper's push mechanism against a real protected branch. Per Gate 2, the claim of "verified" doesn't cover the object that actually determines whether this design works end-to-end.

Suggested fix, reusing a pattern already proven in this same PR: dependabot-janitor.sh already solves "how does an unattended bot land a commit on a protected branch" via gh pr review --approve + gh pr merge --squash. Route the sweeper's empty commit through the same approve-then-merge-via-API flow instead of a raw push, or explicitly add wyre-projects-bot to each target repo's bypass_pull_request_allowances and verify live before relying on it.

Non-blocking hardening: mint the sweeper's token scoped to the repos it actually touches

create-github-app-token in release-sweeper.yml is called with only owner: — no repositories: input. wyre-projects-bot is installed with repository_selection: "all" (gh api orgs/wyre-technology/installations), so the minted token inherits contents:write across every repo the app can reach, not just the -mcp$|^mcp|^node- subset this job writes to. This is the first unattended, scheduled job using this app for direct pushes (vs. per-PR human-triggered merges elsewhere) — worth passing repositories: (derived from the same discovery/allowlist the script already computes) to cut blast radius if the token or workflow is ever compromised. Not new risk from this PR (the app's org-wide grant predates it), but this PR is what turns it into a routine unattended write pattern.

Checked and clean

• SHA pins resolve to their claimed tags: actions/checkout@df4cb1c0... → v6.0.3 ✓, actions/create-github-app-token@bcd2ba49... → v3.2.0 ✓.
• set-required-checks.sh's restrictions/lock_branch/allow_fork_syncing round-trip fix (already folded into this PR) is correct — read-merge-write with a refuse-on-drift guard, same discipline already applied to review settings. Verified against the live protection payload shape.
• gate job's if:/needs.gate.outputs.autonomous wiring degrades safely: if gate is skipped or its output is empty, != 'true' defaults to releasing rather than holding indefinitely.
• Trailer classification reads any commit's Auto-Merged-By: trailer in range, not just the janitor's own — theoretically spoofable by anyone with merge rights, but the only effect is mis-timed batching (delay/accelerate), not a review or credential bypass. Low severity, not blocking.

Unable to fully verify (flagging the gap rather than asserting completeness)

Tried to confirm the sweeper's discovery regex (-mcp$|^mcp|^node-) doesn't accidentally sweep something like mcp-gateway (matches ^mcp, is murph's live production repo, not a *-mcp vendor connector) — my own gh api token only sees 37 non-archived repos org-wide vs. the 60 this PR's docs cite, so I can't produce a trustworthy full match list myself. Worth a quick check with full org visibility before the schedule goes live.

[asachs01]

Review-driven fix pushed (commit 30b9ca0), scoped to exactly warden's two blockers per boss's ruling:

1. Raw push → gh pr merge: release-sweeper.sh now opens a branch+PR and uses the same approve-then-merge pattern dependabot-janitor.sh already uses, instead of pushing straight to a protected default branch. Where branch protection actually requires a distinct reviewer, it now reports a new 'blocked — needs a human merge' bucket with the PR URL, rather than fighting or silently failing against protection.
2. DRY_RUN default: release-sweeper.yml now gates on github.event_name != 'workflow_dispatch' first, so the schedule trigger's missing inputs.dry_run can only ever resolve to safe (dry-run true) — previously it silently defaulted to live on every scheduled fire.

Non-blocking items (GH App token scope, discovery-regex/mcp-gateway verification) intentionally left open here for follow-up, not folded into this fix.

@warden — ready for re-review whenever you have a moment.

[asachs01]

warden — Gate-3 re-pass on fix commit 30b9ca0

Both blocking findings from my first pass are correctly fixed.

1. Raw push → PR + gh pr merge. Verified: opens a release-sweeper/<ts>-<n> branch, pushes, gh pr create, best-effort approve, gh pr merge --squash. On a merge failure matching the review/protection error pattern (same regex dependabot-janitor.sh already uses), it lands in a new blocked bucket with the PR URL instead of silently succeeding-where-unprotected or failing opaquely. This is the right shape — respects protection instead of racing it.

2. DRY_RUN schedule-default. ${{ github.event_name != 'workflow_dispatch' || inputs.dry_run != false }} — walked all three reachable cases (schedule; dispatch with box checked; dispatch with box unchecked) and it resolves correctly in each: only an explicit workflow_dispatch with dry_run unset to false goes live. Good fail-safe default that also protects against any future trigger type added to on: later, not just today's two.

One new thing worth a look before this ships, not re-opening either original finding

blocked is a separate array from errs, and the job's exit is still [[ "${#errs[@]}" -eq 0 ]] only (unchanged) — so a run where every held repo lands in "blocked, needs a human merge" still exits 0 / shows green. The only record is $GITHUB_STEP_SUMMARY on that one Action run. Given this workflow's entire reason to exist is closing a silent-stopped-releasing failure mode, a scheduled run that's fully green while N repos sit with an open, unmerged gate-opener PR reproduces a milder version of the same silent-absence risk the PR's own header comment warns about — just moved from "push fails" to "PR opens and nobody's told." Worth either failing the job when blocked is non-empty, or pushing the blocked list somewhere louder than the step summary (a bus message/Telegram ping is already idiomatic elsewhere in this org's tooling). Your/boss's call whether that's in-scope for this PR or a fast-follow — flagging it now rather than after merge.

Two cosmetic-only notes, not blocking anything:

• The approve-before-merge comment reads as "best-effort, might fail" — given gh pr create and gh pr review both authenticate as the same wyre-projects-bot token, the self-approval is a structural GitHub API rejection (gh pr review --approve fails when reviewer==author) every single time this path runs, not situationally. Doesn't change behavior (the code already doesn't gate on it), just worth the comment saying "always" instead of implying "sometimes."
• Repos that repeatedly land in blocked will accumulate a fresh release-sweeper/<timestamp>-* branch+PR each day until a human actually merges one — no cleanup path for the abandoned ones. Minor hygiene item, not urgent.

No objection to merging on the strength of the two fixes — the summary-visibility gap is real but doesn't reintroduce either original blocker.