feat(ci): gate release PRs on the signed hash list, and cut the tag after merge

[MorningLightMountain713]

Background

fluxbench validates a FluxOS installation by checking its ZelBack tree hash against a list of known-good hashes. Until recently that list was served unsigned and written directly by this repository's CI, and releases were cut by hand: the tag was pushed manually, master kept moving afterwards, and nothing ordered "the hash is published" against "nodes can update to it".

Two merged PRs fixed the first half. fluxhashes#2 made the fluxhashes signer the single writer of the list — deriving every hash itself from commits it fetches from this repository, signing with Ed25519, and keeping a provenance record. #1789 replaced this repository's write access with a dispatch. Both merged on 2026-08-30, and the signer has been publishing continuously since.

This PR is the third piece: it makes the release process respect that ordering — a release PR cannot merge until the tree it ships is already in the signed list, and the tag + GitHub Release become CI outputs cut after verification instead of by hand.

This PR also adds RELEASING.md, which is the process doc from here on. It covers what a releaser does, what each check means, and what every red message is telling you to fix. Nothing else needs to be known to cut a release.

The release process, before and after

	today	with this PR (activated)
the release act	merge the reviewed development → master release PR	unchanged — same PR, same review, same merge button
what is allowed to merge	anything approved	only a candidate whose tree hash is already in the signed list, with the version bumped and the fallback entry present — the gate check
the tag	pushed by hand, sometimes at a different commit than nodes end up running	cut by CI after re-verifying the tree that actually landed on master
GitHub Release	manual, when done at all	published by CI together with the tag
helpers/hashes.json entry	committed straight to master after the tag, outside any pipeline	rides the release PR, enforced by the gate
release provenance	the fluxhashes commit message only	the fluxhashes signer records the tag on the hash's provenance row
a late or failed hash publication	invisible — nodes can update to a tree the list does not yet cover	blocks the merge (before it) or the tag (after it), loudly
master between releases	moves freely; nodes follow HEAD, which can be past the release	moves only through gated release PRs once branch protection is on

release-gate

Runs on PRs targeting master and judges the merge preview — the tree master will actually hold, not the PR branch alone:

• the version moves forward, compared numerically per part: string comparison would call 8.17.10 older than 8.17.9. A version that is not three numeric parts is refused by name rather than judged by whichever part happens to differ — 8.18 has no third part, and 8.18.0-rc1 would otherwise pass on its minor while 8.17.2-rc1 was refused on a NaN.
• the merged ZelBack is a tree the signer can have seen. The merge preview is a ref nowhere, so its hash is in the signed document only because some branch tip already holds the same ZelBack subtree — normally this PR's head. If master carries ZelBack changes development lacks, the merged tree exists on no branch and no signing run can ever cover it; this refuses immediately and names the remedy (merge master into development) instead of letting the next check tell the reader to wait for something that will never arrive. It compares the ZelBack subtree deliberately: master diverging under helpers/ is routine and cannot change the hash.
• the tree hash appears in the signed document central serves, with the signature verified against the published keys — a stale deploy answering every path with the unsigned array is a red run, not a pass.
• helpers/hashes.json carries the hash (old fluxbench's fallback; this check retires with it).

Read-only, no secrets. Enforcement comes from branch protection listing the check as required — the workflow itself has no power to block a merge.

release-tag

Runs on master pushes that change the version, and only on this repository:

• re-verifies the merged tree against the signed document, polling up to 15 minutes. The merge tree normally equals the already-verified PR head tree, so this passes on the first poll. Each retry logs the failure's message rather than its whole stack trace.
• samples ten live nodes' /flux/hashlist — advisory (logged, never fatal) until the fleet serves the endpoint; enforcement is later turning the final failure on.
• pushes the annotated tag, publishes the GitHub Release, and dispatches the tag annotation to the fluxhashes signer, which records it on the hash's provenance row itself.

The dispatch happens here rather than relying on a tag-push trigger, because the tag is pushed with GITHUB_TOKEN — and GITHUB_TOKEN pushes do not trigger workflows. Nothing in this repository writes to fluxhashes; the dispatch token carries Actions permission only.

Idempotency is by commit, not by name. A re-run whose tag already points at this commit has nothing left to do and skips. A tag carrying the release version but pointing somewhere else — cut by hand, or left behind by a master that was rolled back — is not a re-run, and the job stops rather than skipping: skipping would mean the merged tree was never verified and the release reported green with no tag. Both annotated and lightweight tags are resolved, because every tag in this repository today is lightweight while everything this workflow cuts is annotated.

A push that does not change the version is not a release and takes a green no-op path.

Tested

tests/ci/release-workflows.sh runs offline with no secrets, extracts each step from the workflow files verbatim rather than copying it, and mutation-tests its own assertions:

as they ship : 20 passed, 0 failed
mutations    : 11 caught, 0 missed

The eleven mutations each reintroduce one specific defect — a lookup blind to lightweight tags, a whole-tree comparison that over-fires on routine helpers/ divergence, a loosened version pattern, a missing failure guard, a downstream step that stops reading the output the gate writes — and every one is caught by a case asserting the cause, not just the failure. It also asserts that the steps it extracts have no ${{ }} left in them, so a step that becomes uninspectable breaks the tests rather than silently skipping them.

Before that, the whole flow ran on real GitHub in throwaway sandbox repositories with a test key:

release PR opened before publication	gate red: not in the signed document (seq 1)
merge attempted while red	refused by branch protection, against the repo admin
candidate published and signed	gate green: signed document seq 2 carries the tree hash
merge, then release-tag	merged tree hash identical to the PR head hash; tag v8.17.2 and GitHub Release published; provenance row annotated with the tag, original attribution preserved
advisory sample	ten real mainnet nodes, 0 serving — correctly non-fatal
non-release pushes to master	version unchanged, not a release, green

Activation

The prerequisites are complete. fluxhashes#2 and #1789 are merged, the signer has been publishing continuously since 2026-08-30, and hashes.runonflux.io serves the signed document.

Verified end to end on 2026-09-01: development's tip ZelBack hash 06779cc6717187066ab83ee7b1249838 is present in signed document seq 12, so a release cut from development today passes the gate on its first poll.

Order from here:

1. Merge this PR. Nothing changes on merge — release-gate only runs on PRs targeting master, and release-tag only reaches master at the next release.
2. The next release carries both workflows onto master, where release-tag does its work. release-gate runs on that PR but cannot block it yet. Follow RELEASING.md — the one change to the ritual is that the helpers/hashes.json entry now rides the release PR instead of being committed to master afterwards.
3. The old publication credential on this repository can be retired once master carries the post-feat(ci): hash publication becomes a dispatch; flux CI loses write access to fluxhashes #1789 workflow.
4. Add gate to master's required status checks. That is the activation, and it is what makes the check enforcing.

🤖 Generated with Claude Code

[Cabecinha84]

One finding I'd ask to fix before ACK

Tag already cut? will silently swallow the very next release.

Repo state right now:

• master = 8.17.0, development = 8.17.1
• Tag v8.17.1 exists and the GitHub Release v8.17.1 is marked Latest
• v8.17.1 → 60cb6fc (merge of #1773), which is on neither master nor development — master was rolled back behind it

So when the next release PR (development 8.17.1 → master 8.17.0) merges:

1. Did the version change? → 8.17.0 ≠ 8.17.1 → release=true
2. Tag already cut? → git ls-remote --tags origin refs/tags/v8.17.1 succeeds → done=true
3. Every remaining step is skipped: no merged-tree verification, no tag, no Release, no provenance dispatch — and the
   job is green

The result is the exact defect the PR exists to fix — a "Latest" release pointing at an orphan commit that isn't on
master — reported as success, with the authoritative post-merge check (the one the file header calls "the only
divergence branch protection cannot cover") skipped.

The fix is small and doesn't weaken idempotency, because the legitimate re-run case is a re-run on the same commit:

if EXISTING=$(git ls-remote --tags origin "refs/tags/v${V}^{}" | cut -f1) && [ -n "$EXISTING" ]; then
if [ "$EXISTING" = "$GITHUB_SHA" ]; then
echo "done=true" >> "$GITHUB_OUTPUT" # genuine re-run
else
echo "tag v${V} already exists at ${EXISTING}, not this commit"; exit 1
fi
fi

Either that, or clean up the stale v8.17.1 tag/Release before activation — but I'd prefer the code change, since the
same hand-tagging that produced this state can produce it again.

---

Non-blocking notes (worth a comment, not a block)

1. "Safe to merge at any point" is slightly optimistic. A release merged to master before the signing chain is live
   doesn't no-op — it polls the unsigned array for 15 minutes (Buffer.from(undefined,'base64') → TypeError, caught,
   retried ×30), then fails with no tag. Non-releases are genuinely inert; releases in that window are not. The manual
   tag fallback still exists, so it's a red run plus a manual step, but the PR body should say so.
2. The gate needs the merge-preview tree to be a branch tip. The signer reconciles ls-remote --heads --tags only, so
   it signs branch-tip trees. Today master is an ancestor of development, so the merge preview tree == development's
   tip tree and the gate can pass. Any commit landing directly on master (the pre-PR habit — 845aa9b "fluxos
   v8.17.0" was one) creates a merge tree no branch tip holds, which no signing run will ever cover → gate red forever
   until master is merged back into development. This PR actually removes the main source of that divergence
   (hashes.json rides the PR), but the trap deserves a line in the workflow header.
3. Prerelease versions compare inconsistently. 8.17.1 → 8.17.2-rc1 throws (NaN), but 8.17.1 → 8.18.0-rc1 passes (minor
   delta short-circuits before the NaN). Cosmetic — Flux doesn't ship prereleases — but the failure mode is
   arbitrary.
4. ${{ steps.version.outputs.version }} interpolated into run:. Value comes from package.json on master, so it's
   post-review content — real risk is negligible, but reading it via env: instead of ${{ }} costs nothing.
5. The gate is defined in the tree it gates. A release PR can edit release-gate.yml and its own required check reports
   green. Inherent to in-repo required checks, mitigated by human review — worth stating explicitly rather than
   leaving implicit.
6. No github.repository guard on release-tag. Forks pushing to their own master get red runs. Cosmetic.
7. cat poll-error.txt dumps a full Node stack trace per attempt — up to 30 stack traces in the log. head -1 would read
   better.

[MorningLightMountain713]

All eight items are serviced, at 3ee1c829b. RELEASING.md and tests/ci/release-workflows.sh are new on the branch.

The blocking finding — fixed, by commit rather than by name

Tag already cut? now resolves the tag to a commit and compares it to the one being released. The same commit is a genuine re-run and still skips. Anything else stops the job and names both commits, because skipping would mean the merged tree was never verified and the release reported green with no tag.

It reads both refs/tags/vX and refs/tags/vX^{} and prefers the peeled value. Two things made that necessary rather than taking the snippet as written:

• The peeled ref exists only for annotated tags. All 312 tags in this repository are lightweight — including the v8.17.1 that prompted the finding — so a peeled-only lookup matches none of them.
• There is no done=false branch. On the ordinary path nothing is written to $GITHUB_OUTPUT, so every later step's if compares an empty string against 'false' and the release silently no-ops green.

The repository state has also moved since you looked: master is 8.17.1 and 60cb6fca9 is on it, so that particular collision is gone. The class is not, which is why the check is in.

Non-blocking notes

1 — overtaken by events. fluxhashes#2 and #1789 merged about ten minutes after the review. Central serves the signed document, and development's tip ZelBack hash 06779cc6717187066ab83ee7b1249838 is in seq 12 — so a release today verifies on the first poll. The body no longer describes the prerequisites as pending.

2 — taken, as a check rather than a header line. The gate now refuses before it asks central, naming the remedy: merge master into development.

The mechanism is right; the rule is narrower than stated. Master is not an ancestor of development — it is three commits ahead — but the gate hashes ./ZelBack only, and all three touch helpers/. 845aa9b6a is one line of helpers/hashes.json. Of the last 25 commits on master, ten are direct and none touches ZelBack. So the invariant is that the merge preview's ZelBack subtree must match a branch tip's, not that the whole tree must — a whole-tree comparison would block every release following a node-data commit. There is a test case for exactly that, and a mutation proving it bites.

3 — taken and widened. A version that is not three numeric parts is refused by name. 8.18 passed before too, with no third part at all.

4 — taken. No ${{ }} remains inside any run: in either workflow, and the tests assert it.

5 — acknowledged, no change. Inherent to any in-repo required status check. What stands against it is master's required approvals and code-owner review; worth having stated rather than left implicit.

6 — taken. if: github.repository == 'RunOnFlux/flux' on the job, matching the guard #1789 put on nodejs.yml.

7 — taken, with a different command. head -1 returns [eval]:1 — node prints the file marker first and the message about five lines down. It now greps the message line, with head -1 as a fallback so a failure that is not a node error still prints something.

Tests

tests/ci/release-workflows.sh runs offline with no secrets, extracts each step from the workflow files verbatim rather than copying it, and mutation-tests its own assertions.

as they ship : 20 passed, 0 failed
mutations    : 11 caught, 0 missed

One of the mutations is the peeled-only form, so the repository cannot drift back into it unnoticed. The suite also asserts that the steps it extracts carry no ${{ }}, so a step that becomes uninspectable breaks the tests rather than silently skipping them.

[Cabecinha84]

ack