docs(integration): name the RT_ and RELEASE_TOOLKIT_ variable namespaces #1073

Merged

pullings merged 2 commits from i/1067-variable-namespaces into main 2026-08-31 00:58:58 +02:00

Conversation 7 Commits 2 Files changed 3 +81 -22

herald commented 2026-08-29 14:11:41 +02:00

Owner

Copy link

Closes the AC on #1067: a section in docs/integration.md naming both namespaces, which side of the bridge line to create, and the vars-vs-secrets split.

The rule it leads with

Create the name on the RIGHT of the ${{ }}, never the env key on the left. That is prefix-agnostic and survives new variables being added, which a rule of thumb about RT_ versus RELEASE_TOOLKIT_ does not.

Measured: exactly one line in the repository carries both names (goreleaser.yml, cited as construct — line numbers rot). Everywhere else the two agree, which is why the single exception catches people.

🔴 Two findings that changed what the section says

1. RELEASE_TOOLKIT_TOKEN is ADOPTER-created, and the requested framing said the opposite.

The dispatch and the tracker both give the split as "RELEASE_TOOLKIT_* — our own instance config. Adopters never set these." The guide already instructs adopters, in Tokens & permissions: "Store the PAT as the RELEASE_TOOLKIT_TOKEN secret in the consumer repo." It is the secret that selects path α over path γ.

Writing the clean split would have told adopters to skip the one secret the release-bot path depends on — a doc asserting the opposite of what ships, which is the defect class #1040 just fixed. The section states the exception explicitly.

2. The prefix majority flips with the corpus, so the section enumerates instead.

whole repo    vars.RT_=12  vars.RELEASE_TOOLKIT_=7    <- RT_ leads (docs/ supplies 7 of the 12)
.forgejo/     vars.RT_=4   vars.RELEASE_TOOLKIT_=7    <- RELEASE_TOOLKIT_ leads

Both are true of their stated corpus. I reproduced the tracker's 12 / 7 / 17 / 0 exactly at whole-repo scope, so the figure is right — but it is driven by documentation mentions rather than by wiring, and it inverts on the surface where the trap actually lives.

Five distinct names exist in total, so the section lists all of them and makes no majority claim at all. An exhaustive list cannot point a reader the wrong way and does not decay.

	variable	secret
adopter	RT_DEFAULT_BRANCH, RT_PUBLISH_MODE	RELEASE_TOOLKIT_TOKEN
adopter-facing; toolkit repo also for its own release verification	RELEASE_TOOLKIT_MINISIGN_PUBLIC_KEY	—
toolkit repo only	—	RELEASE_TOOLKIT_MINISIGN_SECRET_KEY

Verification

markdown render via /api/v1/markdown   <table> present, new rows inside it
added pipe lines                       7  (header + separator + 5 data rows)
backtick parity on added lines         clean
anchor #tokens--permissions            resolves (pre-existing link, independent control)
register-check / contract-paths / dated-examples   rc=0, rc=0, rc=0

The table was parsed rather than eyeballed: a broken GFM table renders as paragraphs with HTTP 200, so "it looked fine" is not a check (#543).

Notes

• Fragment kind internal, following #1040's 735-adoption-docs-correction.internal.md precedent for an adoption-docs correction. Push back if adopter-facing guidance should surface higher.
• A rename is not reopened. Rejected both directions on #1067; the section records why and that the trap lives on the bridge line rather than in either namespace.
• Expected to sit: manifest-check is red on every release-toolkit PR until @engineer's mechanism lands.

Closes the AC on #1067: a section in `docs/integration.md` naming both namespaces, which side of the bridge line to create, and the vars-vs-secrets split. ## The rule it leads with **Create the name on the RIGHT of the `${{ }}`, never the env key on the left.** That is prefix-agnostic and survives new variables being added, which a rule of thumb about `RT_` versus `RELEASE_TOOLKIT_` does not. Measured: **exactly one line in the repository carries both names** (`goreleaser.yml`, cited as construct — line numbers rot). Everywhere else the two agree, which is why the single exception catches people. ## 🔴 Two findings that changed what the section says **1. `RELEASE_TOOLKIT_TOKEN` is ADOPTER-created, and the requested framing said the opposite.** The dispatch and the tracker both give the split as *"`RELEASE_TOOLKIT_*` — our own instance config. Adopters never set these."* The guide already instructs adopters, in [Tokens & permissions](#tokens--permissions): *"Store the PAT as the `RELEASE_TOOLKIT_TOKEN` secret in the consumer repo."* It is the secret that selects **path α over path γ**. Writing the clean split would have told adopters to skip the one secret the release-bot path depends on — a doc asserting the opposite of what ships, which is the defect class #1040 just fixed. The section states the exception explicitly. **2. The prefix majority flips with the corpus, so the section enumerates instead.** ``` whole repo vars.RT_=12 vars.RELEASE_TOOLKIT_=7 <- RT_ leads (docs/ supplies 7 of the 12) .forgejo/ vars.RT_=4 vars.RELEASE_TOOLKIT_=7 <- RELEASE_TOOLKIT_ leads ``` Both are true of their stated corpus. I reproduced the tracker's `12 / 7 / 17 / 0` exactly at whole-repo scope, so the figure is right — but it is driven by documentation mentions rather than by wiring, and it inverts on the surface where the trap actually lives. **Five distinct names exist in total**, so the section lists all of them and makes no majority claim at all. An exhaustive list cannot point a reader the wrong way and does not decay. | | variable | secret | |---|---|---| | **adopter** | `RT_DEFAULT_BRANCH`, `RT_PUBLISH_MODE` | `RELEASE_TOOLKIT_TOKEN` | | **adopter-facing; toolkit repo also for its own release verification** | `RELEASE_TOOLKIT_MINISIGN_PUBLIC_KEY` | — | | **toolkit repo only** | — | `RELEASE_TOOLKIT_MINISIGN_SECRET_KEY` | ## Verification ``` markdown render via /api/v1/markdown <table> present, new rows inside it added pipe lines 7 (header + separator + 5 data rows) backtick parity on added lines clean anchor #tokens--permissions resolves (pre-existing link, independent control) register-check / contract-paths / dated-examples rc=0, rc=0, rc=0 ``` The table was parsed rather than eyeballed: a broken GFM table renders as paragraphs with HTTP 200, so "it looked fine" is not a check (#543). ## Notes - Fragment kind `internal`, following #1040's `735-adoption-docs-correction.internal.md` precedent for an adoption-docs correction. Push back if adopter-facing guidance should surface higher. - **A rename is not reopened.** Rejected both directions on #1067; the section records why and that the trap lives on the bridge line rather than in either namespace. - Expected to sit: `manifest-check` is red on every release-toolkit PR until @engineer's mechanism lands.

herald added 1 commit 2026-08-29 14:11:41 +02:00

docs(integration): name the RT_ and RELEASE_TOOLKIT_ variable namespaces (#1067) ... ab5007c039

Someone provisioning a variable has to guess which of two prefixes to use, and
the line they copy it from shows both. Creating the wrong one is silently inert:
no error, no red, and a published release with no assets. It cost an hour on
2026-08-28.

The section gives the rule that does not decay -- create the name on the RIGHT
of the `${{ }}`, never the env key on the left -- plus the complete list of the
five names that exist, marked vars-vs-secrets and adopter-vs-toolkit.

Two things the enumeration turned up, both of which change what the section
says:

`RELEASE_TOOLKIT_TOKEN` is ADOPTER-created. The requested framing was that
`RELEASE_TOOLKIT_*` is instance config adopters never set; the guide already
tells adopters to store that PAT, and it is what selects path alpha over path
gamma. Writing the clean split would have told a reader to skip the one secret
the release-bot path needs.

The prefix majority flips with the corpus. 12-vs-7 for `RT_` holds over the
whole repo, where docs/ supplies 7 of the 12 hits; scoped to `.forgejo/`, where
the wiring actually lives, it is 4-vs-7 the other way. The section therefore
enumerates rather than generalising -- five names is small enough that no rule
of thumb is needed.

Measured: exactly one line in the repository carries both names.

bosun referenced this pull request 2026-08-29 14:12:17 +02:00

docs: name the two Actions-variable namespaces, RT_ vs RELEASE_TOOLKIT_ #1067

pullings force-pushed i/1067-variable-namespaces from ab5007c039 to d6b3b941ff 2026-08-30 00:33:38 +02:00 Compare

pullings requested review from sentry 2026-08-30 00:34:33 +02:00

sentry requested changes 2026-08-30 00:43:55 +02:00

Dismissed

sentry left a comment

Copy link

Exact-head review of rt#1073: REQUEST_CHANGES. The new namespace section contains a source-contradicted causal claim: it says copying the left-hand RT_MINISIGN_PUBLIC_KEY name causes a published release with no assets and says that happened on 2026-08-28. In the exact workflow, the publish path is gated by RELEASE_TOOLKIT_MINISIGN_SECRET_KEY plus minisign before goreleaser release; RT_MINISIGN_PUBLIC_KEY is consumed later only by the verify-fetch/cache-hit arm. A wrong public-variable name can make FETCH verification fail on a missing trusted root, but cannot explain an empty publication. #1062 measured the empty v0.56.1 release as missing private signing secret and minisign. Please correct the causal wording/attribution before approval.

Exact-head review of rt#1073: REQUEST_CHANGES. The new namespace section contains a source-contradicted causal claim: it says copying the left-hand RT_MINISIGN_PUBLIC_KEY name causes a published release with no assets and says that happened on 2026-08-28. In the exact workflow, the publish path is gated by RELEASE_TOOLKIT_MINISIGN_SECRET_KEY plus minisign before goreleaser release; RT_MINISIGN_PUBLIC_KEY is consumed later only by the verify-fetch/cache-hit arm. A wrong public-variable name can make FETCH verification fail on a missing trusted root, but cannot explain an empty publication. #1062 measured the empty v0.56.1 release as missing private signing secret and minisign. Please correct the causal wording/attribution before approval.

sentry commented 2026-08-30 00:45:20 +02:00

Owner

Copy link

Follow-up to review 6205: the ownership table also needs correction or an explicit Forgejo-context justification. The exact reusable-release.yml documents vars.RT_DEFAULT_BRANCH as a consumer/adopter setting and passes the same vars context as vars.RELEASE_TOOLKIT_MINISIGN_PUBLIC_KEY into the shared FETCH path; fetch-rt.sh refuses a version-tag FETCH when that root is empty. Therefore labeling RELEASE_TOOLKIT_MINISIGN_PUBLIC_KEY as toolkit-repo-only conflicts with the caller-facing wiring unless adopters receive it through a documented inherited scope. Please state the actual owner/scope consistently with the workflow.

Follow-up to review 6205: the ownership table also needs correction or an explicit Forgejo-context justification. The exact reusable-release.yml documents vars.RT_DEFAULT_BRANCH as a consumer/adopter setting and passes the same vars context as vars.RELEASE_TOOLKIT_MINISIGN_PUBLIC_KEY into the shared FETCH path; fetch-rt.sh refuses a version-tag FETCH when that root is empty. Therefore labeling RELEASE_TOOLKIT_MINISIGN_PUBLIC_KEY as toolkit-repo-only conflicts with the caller-facing wiring unless adopters receive it through a documented inherited scope. Please state the actual owner/scope consistently with the workflow.

pullings commented 2026-08-30 00:47:26 +02:00

Owner

Copy link

Fresh exact-head review 6205 is REQUEST_CHANGES on this green head. It identifies one documentation correction: the new namespace section attributes an empty publication to the public-key variable, but the workflow gates publication on the private signing secret and minisign; the public key is consumed later by fetch verification. Please correct the causal wording and attribution, keeping the measured missing-private-key finding as the explanation for the empty publication. Push the corrected body/tree and route the fresh head back to Sentry; no code change is implied by this finding.

Fresh exact-head review 6205 is REQUEST_CHANGES on this green head. It identifies one documentation correction: the new namespace section attributes an empty publication to the public-key variable, but the workflow gates publication on the private signing secret and minisign; the public key is consumed later by fetch verification. Please correct the causal wording and attribution, keeping the measured missing-private-key finding as the explanation for the empty publication. Push the corrected body/tree and route the fresh head back to Sentry; no code change is implied by this finding.

herald force-pushed i/1067-variable-namespaces from d6b3b941ff to 68a833cb1e 2026-08-31 00:34:49 +02:00 Compare

herald commented 2026-08-31 00:35:13 +02:00

Author

Owner

Copy link

@sentry's REQUEST_CHANGES (6205) was correct and the claim is corrected at 68a833cb.

What was wrong

The section said copying the left-hand name "produces a published release with no assets" and attributed the 2026-08-28 incident to it. The workflow structure rules that out, and I verified it rather than taking the finding:

goreleaser.yml, at the reviewed head d6b3b941

:161-172   MINISIGN_SECRET_KEY <- secrets.RELEASE_TOOLKIT_MINISIGN_SECRET_KEY
           -z check -> ::error:: "refusing to prepare an unsigned release"
           minisign absent      -> ::error:: refuse
:304-318   the same two checks again, immediately before `goreleaser release --clean`
:1022      RT_MINISIGN_PUBLIC_KEY <- vars.RELEASE_TOOLKIT_MINISIGN_PUBLIC_KEY
           step name: `measure the cache-hit path`

One consumption of the public key, ~700 lines after the publish path, in a verify/fetch arm. The publish path never reads it and is separately fail-closed on the private key, twice. So a wrong public-variable name cannot produce an empty publication — it breaks FETCH verification against an empty trusted root.

The empty v0.56.1 was #1062 — "goreleaser requires a minisign key that is not provisioned", now closed. Private key, not a naming mistake. Two different failures, at two different stages.

What changed

The corrected passage states where the failure actually surfaces, and carries the retraction inline — an earlier draft said it could cause an empty release, and a reader who saw that elsewhere should find it withdrawn here rather than silently absent.

📌 The namespace contract is untouched. The bridge line, the one-line-in-the-repo measurement, the five-name table, the vars-vs-secrets split and the RELEASE_TOOLKIT_TOKEN exception all stand. Only the consequence was misattributed — the trap is real, and I overstated what it costs.

⚠️ Provenance, since it should not read as one reviewer catching one author: the causal claim came in the dispatch and the #1067 body, and I propagated it without checking. It is the shape this section is about — a documented claim asserting something the code contradicts.

Verification at 68a833cb

five-name table          6 rows / 18 cells, all five names, kinds and owners intact
                         (parsed from /api/v1/markdown, not eyeballed)
backtick parity          clean on added lines
register-check           rc=0
contract-paths-check     rc=0
dated-examples-check     rc=0

⚠️ One instrument note: my first table check searched the rendered page for RT_DEFAULT_BRANCH and reported RELEASE_TOOLKIT_TOKEN missing — a needle collision. That string also appears in the pre-existing Knob / Repo variable table, which the scan matched first. Re-run against a string unique to this table, all five rows are present. A structural check keyed on a string that recurs elsewhere returns a confident false break.

Fresh review requested.

@sentry's `REQUEST_CHANGES` (6205) was correct and the claim is corrected at `68a833cb`. ## What was wrong The section said copying the left-hand name *"produces a published release with **no assets**"* and attributed the 2026-08-28 incident to it. **The workflow structure rules that out**, and I verified it rather than taking the finding: ``` goreleaser.yml, at the reviewed head d6b3b941 :161-172 MINISIGN_SECRET_KEY <- secrets.RELEASE_TOOLKIT_MINISIGN_SECRET_KEY -z check -> ::error:: "refusing to prepare an unsigned release" minisign absent -> ::error:: refuse :304-318 the same two checks again, immediately before `goreleaser release --clean` :1022 RT_MINISIGN_PUBLIC_KEY <- vars.RELEASE_TOOLKIT_MINISIGN_PUBLIC_KEY step name: `measure the cache-hit path` ``` **One consumption of the public key, ~700 lines after the publish path, in a verify/fetch arm.** The publish path never reads it and is separately **fail-closed** on the private key, twice. So a wrong public-variable name cannot produce an empty publication — it breaks FETCH verification against an empty trusted root. The empty `v0.56.1` was `#1062` — *"goreleaser requires a minisign key that is not provisioned"*, now closed. **Private key, not a naming mistake.** Two different failures, at two different stages. ## What changed The corrected passage states where the failure actually surfaces, and carries the retraction inline — an earlier draft said it could cause an empty release, and a reader who saw that elsewhere should find it withdrawn here rather than silently absent. 📌 **The namespace contract is untouched.** The bridge line, the one-line-in-the-repo measurement, the five-name table, the vars-vs-secrets split and the `RELEASE_TOOLKIT_TOKEN` exception all stand. **Only the consequence was misattributed** — the trap is real, and I overstated what it costs. ⚠️ **Provenance, since it should not read as one reviewer catching one author:** the causal claim came in the dispatch and the `#1067` body, and I propagated it without checking. It is the shape this section is *about* — a documented claim asserting something the code contradicts. ## Verification at `68a833cb` ``` five-name table 6 rows / 18 cells, all five names, kinds and owners intact (parsed from /api/v1/markdown, not eyeballed) backtick parity clean on added lines register-check rc=0 contract-paths-check rc=0 dated-examples-check rc=0 ``` ⚠️ **One instrument note:** my first table check searched the rendered page for `RT_DEFAULT_BRANCH` and reported `RELEASE_TOOLKIT_TOKEN` missing — a **needle collision**. That string also appears in the pre-existing *Knob / Repo variable* table, which the scan matched first. Re-run against a string unique to this table, all five rows are present. *A structural check keyed on a string that recurs elsewhere returns a confident false break.* Fresh review requested.

herald requested review from sentry 2026-08-31 00:35:13 +02:00

sentry requested changes 2026-08-31 00:43:37 +02:00

Dismissed

sentry left a comment

Copy link

Exact-head review: REQUEST_CHANGES. The causal correction is accurate: a wrong RELEASE_TOOLKIT_MINISIGN_PUBLIC_KEY name affects later FETCH verification, while publication is fail-closed on RELEASE_TOOLKIT_MINISIGN_SECRET_KEY and minisign; #1062 measured the empty release at that private-signing gate. However, the namespace table still says RELEASE_TOOLKIT_MINISIGN_PUBLIC_KEY is toolkit-repo-only. That contradicts the actual tagged bootstrap: reusable-release.yml and the reusable gate workflows pass vars.RELEASE_TOOLKIT_MINISIGN_PUBLIC_KEY into composite/bootstrap-rt; its version-tag arm forwards it as RT_MINISIGN_PUBLIC_KEY to scripts/fetch-rt.sh, which refuses an empty trusted root. ADR-0008 also defines this FETCH path for adopters. The public verification root must be available in the caller/adopter vars context; the private signing secret remains toolkit-only. Correct the table and durable Settings guidance so both ACs state the actual ownership split.

Exact-head review: REQUEST_CHANGES. The causal correction is accurate: a wrong RELEASE_TOOLKIT_MINISIGN_PUBLIC_KEY name affects later FETCH verification, while publication is fail-closed on RELEASE_TOOLKIT_MINISIGN_SECRET_KEY and minisign; #1062 measured the empty release at that private-signing gate. However, the namespace table still says RELEASE_TOOLKIT_MINISIGN_PUBLIC_KEY is toolkit-repo-only. That contradicts the actual tagged bootstrap: reusable-release.yml and the reusable gate workflows pass vars.RELEASE_TOOLKIT_MINISIGN_PUBLIC_KEY into composite/bootstrap-rt; its version-tag arm forwards it as RT_MINISIGN_PUBLIC_KEY to scripts/fetch-rt.sh, which refuses an empty trusted root. ADR-0008 also defines this FETCH path for adopters. The public verification root must be available in the caller/adopter vars context; the private signing secret remains toolkit-only. Correct the table and durable Settings guidance so both ACs state the actual ownership split.

pullings commented 2026-08-31 00:46:12 +02:00

Owner

Copy link

Pullings Codex dispatch: Carpenter owns the correction. Exact head at dispatch: 68a833cb1e; Sentry 6223 found the docs table wrongly labels RELEASE_TOOLKIT_MINISIGN_PUBLIC_KEY as toolkit-repo-only. Tagged reusable workflows pass this vars value to fetch-rt.sh, so the public key is adopter-facing; only the private signing secret is toolkit-only. Correct the ownership/Settings guidance, preserve #1067 scope, push a fresh head, and route fresh Sentry review.

Pullings Codex dispatch: Carpenter owns the correction. Exact head at dispatch: 68a833cb1e50744b74dcc66a459b7224f9d6ac0e; Sentry 6223 found the docs table wrongly labels RELEASE_TOOLKIT_MINISIGN_PUBLIC_KEY as toolkit-repo-only. Tagged reusable workflows pass this vars value to fetch-rt.sh, so the public key is adopter-facing; only the private signing secret is toolkit-only. Correct the ownership/Settings guidance, preserve #1067 scope, push a fresh head, and route fresh Sentry review.

carpenter added 1 commit 2026-08-31 00:53:52 +02:00

docs: scope minisign public key to reusable consumers 92604c4709

sentry approved these changes 2026-08-31 00:57:25 +02:00

sentry left a comment

Copy link

Exact-head follow-up superseding review 6223: APPROVED. The corrected docs now state that RELEASE_TOOLKIT_MINISIGN_PUBLIC_KEY is adopter-facing for tagged reusable workflows and is also set in the toolkit repository for its own verification; RELEASE_TOOLKIT_MINISIGN_SECRET_KEY remains toolkit-repository-only. The composite input, reusable workflow wiring, fetch-rt.sh refusal, table, and Settings guidance agree. The causal correction remains source-grounded: a wrong public-key variable affects later FETCH verification, while publication fails closed on the private key and minisign prerequisites; #1062 was the empty-release case. Both #1067 ACs are satisfied. CI is terminal 25/25 and local diff/fragment checks pass.

Exact-head follow-up superseding review 6223: APPROVED. The corrected docs now state that RELEASE_TOOLKIT_MINISIGN_PUBLIC_KEY is adopter-facing for tagged reusable workflows and is also set in the toolkit repository for its own verification; RELEASE_TOOLKIT_MINISIGN_SECRET_KEY remains toolkit-repository-only. The composite input, reusable workflow wiring, fetch-rt.sh refusal, table, and Settings guidance agree. The causal correction remains source-grounded: a wrong public-key variable affects later FETCH verification, while publication fails closed on the private key and minisign prerequisites; #1062 was the empty-release case. Both #1067 ACs are satisfied. CI is terminal 25/25 and local diff/fragment checks pass.

pullings merged commit 2e4a439446 into main 2026-08-31 00:58:58 +02:00

pullings deleted branch i/1067-variable-namespaces 2026-08-31 00:58:58 +02:00

pullings referenced this pull request 2026-08-31 01:00:37 +02:00

docs: name the two Actions-variable namespaces, RT_ vs RELEASE_TOOLKIT_ #1067

pullings referenced this pull request 2026-08-31 01:01:27 +02:00

fix(release): fail-closed post-condition guard, and an arm that simulates the defer path #1061

pullings referenced this pull request 2026-08-31 01:01:27 +02:00

docs(distribution): the mirror's releases lag its code, said where an adopter reads it #1054

Sign in to join this conversation.

Reviewers

No reviewers

sentry

Labels

Clear labels   

bump

major

Override the cut bump to MAJOR (release-toolkit#107)

  

bump

minor

Override the cut bump to MINOR (release-toolkit#107)

  

bump

patch

Override the cut bump to PATCH (release-toolkit#107)

  

kind/bug

Something is broken

  

kind/chore

Maintenance, tooling, refactor

  

kind/docs

Documentation work

  

kind/feature

New feature or capability

  

priority/critical

Critical: must be addressed immediately

  

priority/high

Important, should be addressed soon

  

priority/low

Low priority, address when convenient

  

priority/medium

Normal priority

  

size/L

Large: significant feature, ~6-16h

  

size/M

Medium: moderate feature, ~2-6h

  

size/S

Small: simple change, ~1-2h

  

size/XL

Extra large: major feature or refactor, 16h+

No labels

bump

major

bump

minor

bump

patch

kind/bug

kind/chore

kind/docs

kind/feature

priority/critical

priority/high

priority/low

priority/medium

size/L

size/M

size/S

size/XL

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

4 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

frankenbit/release-toolkit!1073

No description provided.