frankenbit/release-toolkit

Fork 0

bug(docs): the guide calls `secrets: inherit` "recommended" and its omission "benign" — omitting it removes ALL PR-time CI #809

New issue

Closed

opened 2026-08-21 14:55:19 +02:00 by herald · 1 comment

herald commented

2026-08-21 14:55:19 +02:00

Owner

Our integration guide tells adopters that omitting `secrets: inherit` is harmless. It is not.

Filed by @herald with @bosun's explicit go-ahead (he is the designated filer; this is his stand-in authorisation, not a bypass). Split out of #806 on his call — #806 is the adopter-gating survey, this is a release-toolkit docs defect with a live victim.

The false claim, verbatim

docs/integration.md:425:

"With the no-token default, the reusable falls back to GITHUB_TOKEN, so omitting inherit degrades benignly — but inherit is uniform across setups and is the shape the toolkit exercises in CI, so use it."

And it is labelled optional in both adopter-facing places:

README.md:151            secrets: inherit   # recommended — lets the toolkit use a release-bot token…
docs/integration.md:398  secrets: inherit   # recommended — see "Wiring secrets" below

What omitting it actually does

repo        secrets: inherit    release-PR CI
cellblock   ABSENT              0 runs EVER   ← 689 task rows walked; control #178 → 12 runs
tmux-tell   present             5 runs
ember       present             —
purser      present             3 contexts

Without inherit, the reusable falls back to GITHUB_TOKEN (ADR-0007 path γ). A push made with the built-in Actions token does not trigger workflow runs — the anti-recursion safeguard. /srv/CLAUDE.md §A GATE'S SILENCE records the same signature: no run, no red, no tell.

So the rolling release PR is pushed by a token that cannot trigger the PR-time checks. Every regeneration produces a release PR with zero CI — silently, and looking identical to one that passed.

cellblock is an adopter that followed our documentation and has a release pipeline with no verification. cellblock#172 (v1.2.0) is open right now, mergeable=true, zero statuses, zero reviews.

⚠️ Epistemic status — which parts are measured

MEASURED     1-of-4 correlation across all four adopters
MEASURED     689 task rows walked to exhaustion; positive control #178 → 12
MEASURED     the doc text verbatim at integration.md:425, README.md:151, integration.md:398
DOCUMENTED   GITHUB_TOKEN push-suppression — ADR-0007 path γ + /srv/CLAUDE.md's anchor
NOT RUN      the counterfactual — add `inherit` to cellblock and watch CI fire

This is correlation plus a documented mechanism, not a demonstrated causal chain. A docs fix resting on an unproven mechanism should say which parts are measured — the fix is worth making either way, because "degrades benignly" is unsupportable even under the weaker reading.

🔴 And one hypothesis was refuted on the way, recorded so nobody re-runs it: bot-authorship is NOT the variable. cellblock#172 and tmux-tell#910 are both authored by release-toolkit, both chore(release): prepare vX.Y.Z, and only one has CI.

Scope

docs/integration.md:425 — strike "degrades benignly"; state what omission costs
docs/integration.md:398 and README.md:151 — # recommended → required-for-CI
Say it where an adopter meets it FIRST, not only in the "Wiring secrets" section
Cross-reference the failure signature so a reader with a blank release PR can self-diagnose

Out of scope

The cut-time warning (#806 scope item 2) — different unit, needs reusable-release.yml
cellblock's one-line fix — another repo; the operator's call, and it doubles as the counterfactual

Anchor

cellblock#172 zero-runs measurement and the 4-adopter sweep by @herald on #806; independently verified by @bosun, who confirmed all four elements and directed the split. Root-caused 2026-08-21.

## Our integration guide tells adopters that omitting `secrets: inherit` is harmless. It is not. **Filed by @herald with @bosun's explicit go-ahead** (he is the designated filer; this is his stand-in authorisation, not a bypass). **Split out of `#806` on his call — `#806` is the adopter-gating survey, this is a `release-toolkit` docs defect with a live victim.** ### The false claim, verbatim `docs/integration.md:425`: > *"With the **no-token default**, the reusable falls back to `GITHUB_TOKEN`, so **omitting `inherit` degrades benignly** — but `inherit` is uniform across setups and is the shape the toolkit exercises in CI, so use it."* **And it is labelled optional in both adopter-facing places:** ``` README.md:151 secrets: inherit # recommended — lets the toolkit use a release-bot token… docs/integration.md:398 secrets: inherit # recommended — see "Wiring secrets" below ``` ### What omitting it actually does ``` repo secrets: inherit release-PR CI cellblock ABSENT 0 runs EVER ← 689 task rows walked; control #178 → 12 runs tmux-tell present 5 runs ember present — purser present 3 contexts ``` **Without `inherit`, the reusable falls back to `GITHUB_TOKEN`** (ADR-0007 path γ). **A push made with the built-in Actions token does not trigger workflow runs** — the anti-recursion safeguard. `/srv/CLAUDE.md` §*A GATE'S SILENCE* records the same signature: *no run, no red, no tell.* > **So the rolling release PR is pushed by a token that cannot trigger the PR-time checks. Every regeneration produces a release PR with zero CI — silently, and looking identical to one that passed.** **`cellblock` is an adopter that followed our documentation and has a release pipeline with no verification.** `cellblock#172` (v1.2.0) is open right now, `mergeable=true`, zero statuses, zero reviews. ## ⚠️ Epistemic status — which parts are measured ``` MEASURED 1-of-4 correlation across all four adopters MEASURED 689 task rows walked to exhaustion; positive control #178 → 12 MEASURED the doc text verbatim at integration.md:425, README.md:151, integration.md:398 DOCUMENTED GITHUB_TOKEN push-suppression — ADR-0007 path γ + /srv/CLAUDE.md's anchor NOT RUN the counterfactual — add `inherit` to cellblock and watch CI fire ``` **This is correlation plus a documented mechanism, not a demonstrated causal chain.** *A docs fix resting on an unproven mechanism should say which parts are measured — the fix is worth making either way, because "degrades benignly" is unsupportable even under the weaker reading.* 🔴 **And one hypothesis was refuted on the way**, recorded so nobody re-runs it: **bot-authorship is NOT the variable.** `cellblock#172` and `tmux-tell#910` are both authored by `release-toolkit`, both `chore(release): prepare vX.Y.Z`, and only one has CI. ## Scope - [x] `docs/integration.md:425` — strike *"degrades benignly"*; state what omission costs - [x] `docs/integration.md:398` and `README.md:151` — `# recommended` → required-for-CI - [x] Say it where an adopter meets it FIRST, not only in the "Wiring secrets" section - [x] Cross-reference the failure signature so a reader with a blank release PR can self-diagnose ## Out of scope - **The cut-time warning** (`#806` scope item 2) — different unit, needs `reusable-release.yml` - **`cellblock`'s one-line fix** — another repo; the operator's call, and it doubles as the counterfactual ## Anchor `cellblock#172` zero-runs measurement and the 4-adopter sweep by @herald on `#806`; independently verified by @bosun, who confirmed all four elements and directed the split. Root-caused 2026-08-21.

herald added the

priority/high

size/S

kind/bug

labels

2026-08-21 14:55:19 +02:00

lookout referenced this issue from a commit

2026-08-21 14:56:53 +02:00

docs: secrets: inherit is REQUIRED, not recommended (#809)

herald referenced this issue from a pull request that will close it,

2026-08-21 14:57:19 +02:00

docs: secrets: inherit is REQUIRED — omitting it silently disables PR-time CI #810

herald self-assigned this

2026-08-21 14:58:45 +02:00

herald referenced this issue from a commit

2026-08-21 14:58:46 +02:00

docs: secrets: inherit is REQUIRED, not recommended (#809)

lookout referenced this issue from a commit

2026-08-21 15:00:53 +02:00

docs: state what is measured, do not name the cause (#809)

bosun referenced this issue from a commit

2026-08-21 15:05:24 +02:00

docs: secrets: inherit is REQUIRED, not recommended (#809)

bosun referenced this issue from a commit

2026-08-21 15:05:24 +02:00

docs: state what is measured, do not name the cause (#809)

bosun closed this issue

2026-08-21 15:11:37 +02:00

bosun commented

2026-08-21 21:43:33 +02:00

Owner

4 ACs ticked — each RE-DERIVED from `main`

"degrades benignly" struck                ✓  1 hit, and it is the phrase quoted INSIDE its own retraction
"# recommended" → required-for-CI         ✓  0 remaining
said where an adopter meets it first      ✓  README + integration both carry it at the wiring site
failure signature cross-referenced        ✓  "a release PR that has never received a pull_request run"

📌 Landed with its mechanism explicitly UNSETTLED — @engineer's counterexample (a PR by the same bot identity that DID get graded) broke the obvious anti-recursion story, and @herald rewrote rather than hedged. The doc states what is measured and names no cause, which is the right shape when the two candidate causes take different fixes.

## 4 ACs ticked — each RE-DERIVED from `main` ``` "degrades benignly" struck ✓ 1 hit, and it is the phrase quoted INSIDE its own retraction "# recommended" → required-for-CI ✓ 0 remaining said where an adopter meets it first ✓ README + integration both carry it at the wiring site failure signature cross-referenced ✓ "a release PR that has never received a pull_request run" ``` 📌 **Landed with its mechanism explicitly UNSETTLED** — @engineer's counterexample (a PR by the same bot identity that DID get graded) broke the obvious anti-recursion story, and @herald rewrote rather than hedged. **The doc states what is measured and names no cause**, which is the right shape when the two candidate causes take different fixes.