#1094 - feat(auth): allow a SPLIT credential pair — repo-scoped deploy key for pushes, narrow PAT for the API - frankenbit/release-toolkit

bosun commented

2026-09-04 00:00:29 +02:00

Owner

Today a consumer supplies one credential that does two different jobs — it pushes commits and tags over git, and it creates releases and uploads assets over the API. On Gitea and Forgejo those two jobs can be served by credentials with very different blast radii, and we currently force the broader one on anybody who needs either.

:346  export FORGEJO_TOKEN="${RELEASE_TOKEN_OVERRIDE:-$GITHUB_TOKEN_DEFAULT}"

What is available, measured 2026-09-03

deploy key, write, HTTP    git transport ONLY
                           -> Authorization: token <key> against /api/v1/…/releases = 401
                           repo-scoped BY CONSTRUCTION
user PAT, write:repository git AND api
                           scoped by CATEGORY, not by repo: reaches every repo
                           that user can access
auto-injected token        git AND api, repo-scoped, ephemeral, zero setup
                           but its PUSH does NOT trigger downstream workflows

That last line is why this matters rather than being tidy. goreleaser.yml is on: push: tags: ['v*'], so the cut's tag push must trigger a build to publish assets. Under the auto token that trigger is suppressed by anti-recursion, and the adopter gets a tag with no assets — the exact shape release-toolkit itself shipped as v0.56.1 and spent a week repairing.

So an adopter who wants assets needs a non-auto credential, and today the only option we offer is a token broader than the job.

Proposed — a THIRD option, not a replacement

TIER 1  nothing set              auto token          most convenient, no downstream trigger
TIER 2  RELEASE_TOOLKIT_TOKEN    one PAT             CURRENT behaviour, unchanged
TIER 3  deploy key + narrow PAT  split credentials   least privilege, OPT-IN

🔴 TIER 2 STAYS THE DEFAULT FOR ANYONE WHO SETS ONE TOKEN, AND TIER 1 STAYS THE DEFAULT FOR ANYONE WHO SETS NONE. This adds a path; it does not migrate anybody. For most adopters a single token is the better trade and the docs should say so plainly rather than steering everyone to the complex option because it is the more careful-sounding one.

Acceptance criteria

A consumer may supply a git credential and an API credential separately; supplying one token preserves current behavior. Verified by merged PR #1100 (merge commit 026d985f06) and its tier truth-table controls.
The git half accepts a repo-scoped deploy key. Verified by merged PR #1100 and its tier-3 credential controls.
The resolution order is stated in one place, including operation-specific credentials and half-configured refusal. Verified by merged PR #1100.
integration.md presents all three tiers with convenience/blast-radius tradeoffs and keeps tier 3 opt-in. Verified by merged PR #1100.
Arms cover none/one/both/git-only/api-only, with named refusal for a half-configured adopter. Verified by merged PR #1100.
Mutation controls confirm each arm reddens its own branch without cross-arming. Verified by merged PR #1100.

Bounds

⚠️ write:repository is the narrowest API category Gitea offers for this work, so tier 3 bounds the PUSH surface fully and the API surface only as far as the owning account's reach. Say that in the docs rather than implying tier 3 is repo-scoped end to end — an overstated security property is worse than an absent one.

📌 Deliberately NOT on the Adoption milestone. An adopter can adopt today with a single token; this improves posture for those who want it. Per #1068, anything that does not block the five-point test is not the road. Filed off-milestone on purpose — twice today I added trackers to that milestone that did not belong there.

📌 Anti-recursion behaviour on a deploy-key push is assumed, not measured — a non-bot push should escape the suppression, and that is the premise tier 3 rests on. Measure it before building, because if it does not hold, tier 3 buys only the push-scoping and not the trigger.

Requested by the operator, who asked specifically that it stay optional: "for all the others the convenience of a single token may be the better choice."

Closeout

Implemented and merged by release-toolkit PR #1100 (merge commit 026d985f06; current main also contains it). Official review 6274 and 26/26 required contexts were successful. Tier 2 remains the recommended path; the separate deploy-key whitelist gradeability gap is tracked in #1105 and is not part of this implementation.

Today a consumer supplies **one** credential that does two different jobs — it pushes commits and tags over git, and it creates releases and uploads assets over the API. On Gitea and Forgejo those two jobs can be served by credentials with very different blast radii, and we currently force the broader one on anybody who needs either. ``` :346 export FORGEJO_TOKEN="${RELEASE_TOKEN_OVERRIDE:-$GITHUB_TOKEN_DEFAULT}" ``` ## What is available, measured 2026-09-03 ``` deploy key, write, HTTP git transport ONLY -> Authorization: token <key> against /api/v1/…/releases = 401 repo-scoped BY CONSTRUCTION user PAT, write:repository git AND api scoped by CATEGORY, not by repo: reaches every repo that user can access auto-injected token git AND api, repo-scoped, ephemeral, zero setup but its PUSH does NOT trigger downstream workflows ``` That last line is why this matters rather than being tidy. `goreleaser.yml` is `on: push: tags: ['v*']`, so the cut's tag push **must** trigger a build to publish assets. Under the auto token that trigger is suppressed by anti-recursion, and the adopter gets **a tag with no assets** — the exact shape release-toolkit itself shipped as v0.56.1 and spent a week repairing. So an adopter who wants assets needs a non-auto credential, and today the only option we offer is a token broader than the job. ## Proposed — a THIRD option, not a replacement ``` TIER 1 nothing set auto token most convenient, no downstream trigger TIER 2 RELEASE_TOOLKIT_TOKEN one PAT CURRENT behaviour, unchanged TIER 3 deploy key + narrow PAT split credentials least privilege, OPT-IN ``` 🔴 **TIER 2 STAYS THE DEFAULT FOR ANYONE WHO SETS ONE TOKEN, AND TIER 1 STAYS THE DEFAULT FOR ANYONE WHO SETS NONE. This adds a path; it does not migrate anybody.** For most adopters a single token is the better trade and the docs should say so plainly rather than steering everyone to the complex option because it is the more careful-sounding one. ## Acceptance criteria - [x] A consumer may supply a git credential and an API credential separately; supplying one token preserves current behavior. Verified by merged PR #1100 (merge commit 026d985f06fb84743fee5a53cd723b6fc0bdd0a3) and its tier truth-table controls. - [x] The git half accepts a repo-scoped deploy key. Verified by merged PR #1100 and its tier-3 credential controls. - [x] The resolution order is stated in one place, including operation-specific credentials and half-configured refusal. Verified by merged PR #1100. - [x] integration.md presents all three tiers with convenience/blast-radius tradeoffs and keeps tier 3 opt-in. Verified by merged PR #1100. - [x] Arms cover none/one/both/git-only/api-only, with named refusal for a half-configured adopter. Verified by merged PR #1100. - [x] Mutation controls confirm each arm reddens its own branch without cross-arming. Verified by merged PR #1100. ## Bounds ⚠️ **`write:repository` is the narrowest API category Gitea offers for this work, so tier 3 bounds the PUSH surface fully and the API surface only as far as the owning account's reach.** Say that in the docs rather than implying tier 3 is repo-scoped end to end — an overstated security property is worse than an absent one. 📌 **Deliberately NOT on the Adoption milestone.** An adopter can adopt today with a single token; this improves posture for those who want it. Per #1068, anything that does not block the five-point test is not the road. *Filed off-milestone on purpose — twice today I added trackers to that milestone that did not belong there.* 📌 Anti-recursion behaviour on a deploy-key push is **assumed, not measured** — a non-bot push *should* escape the suppression, and that is the premise tier 3 rests on. Measure it before building, because if it does not hold, tier 3 buys only the push-scoping and not the trigger. Requested by the operator, who asked specifically that it stay optional: *"for all the others the convenience of a single token may be the better choice."* ## Closeout Implemented and merged by release-toolkit PR #1100 (merge commit 026d985f06fb84743fee5a53cd723b6fc0bdd0a3; current main also contains it). Official review 6274 and 26/26 required contexts were successful. Tier 2 remains the recommended path; the separate deploy-key whitelist gradeability gap is tracked in #1105 and is not part of this implementation.

bosun added the

priority/medium

size/M

kind/feature

labels

2026-09-04 00:00:29 +02:00

bosun commented

2026-09-04 00:43:58 +02:00

Author

Owner

✅ THE PREMISE THIS TRACKER RESTS ON IS NOW MEASURED, NOT ASSUMED — AND IT HOLDS. Deploy-key pushes DO escape anti-recursion suppression. So tier 3 buys the downstream trigger, not merely push-scoping, and it is worth building.

Two arms on gitea.com/FrankenBit/tic-tac-toe, both pushing a tag from inside a workflow run, one variable:

ARM A  auto token   tag t-probe-auto-865439     -> ZERO downstream runs
ARM B  deploy key   tag t-probe-deploy-865505   -> downstream run CREATED and SUCCEEDED

Re-checkable after the artifacts were removed:

arm A pusher    task 315504
arm B pusher    task 315523   run 865505
DOWNSTREAM      task 315525   run 865509
                head_branch=t-probe-deploy-865505  event=push  status=success

The downstream run's ref is the deploy tag by name, so it binds to arm B and to nothing else in the history. Run-created-but-unclaimed was excluded the same way arm A excluded it: zero runs in a non-terminal state.

The isolation was verified rather than assumed, and the hazard was live. actions/checkout DID write the auto token into the local config — git config --local http.https://gitea.com/.extraheader AUTHORIZATION: basic *** appears in the log — and then removed it itself, because persist-credentials: false makes checkout clean up in its own step. Without a control there would have been checkout's write in the log and no way to show it was gone by push time:

in-run   http.* local (none) · global (none) · credential.helper (none)
NEGATIVE fabricated key  rc=128  remote: Failed to authenticate user
POSITIVE real key, same refs/probe namespace  rc=0
lengths  deploy 47, fabricated 44 — distinct, so the arms cannot be the same credential

⚠️ What this does NOT change: the API-surface bound above stands unaltered. write:repository is still the narrowest category Gitea offers, so tier 3 bounds the push surface fully and the API surface only as far as the owning account's reach. Tier 2 stays the default and tier 1 stays the default for anyone who sets nothing.

📌 Reusable, and cheaper than this test was: a push to a ref outside refs/heads/* and refs/tags/* authorizes exactly like any push and triggers no workflow — measured, run count unchanged across a create and two deletes. refs/probe/<name> is a zero-cost write-capability probe.

Measured by @quartermaster. Arms, controls and cleanup are his; the checkout-extraheader hazard was flagged before the run and proved live.

✅ **THE PREMISE THIS TRACKER RESTS ON IS NOW MEASURED, NOT ASSUMED — AND IT HOLDS. Deploy-key pushes DO escape anti-recursion suppression.** So tier 3 buys the downstream trigger, not merely push-scoping, and it is worth building. Two arms on `gitea.com/FrankenBit/tic-tac-toe`, both pushing a tag **from inside a workflow run**, one variable: ``` ARM A auto token tag t-probe-auto-865439 -> ZERO downstream runs ARM B deploy key tag t-probe-deploy-865505 -> downstream run CREATED and SUCCEEDED ``` Re-checkable after the artifacts were removed: ``` arm A pusher task 315504 arm B pusher task 315523 run 865505 DOWNSTREAM task 315525 run 865509 head_branch=t-probe-deploy-865505 event=push status=success ``` The downstream run's ref is the deploy tag **by name**, so it binds to arm B and to nothing else in the history. Run-created-but-unclaimed was excluded the same way arm A excluded it: zero runs in a non-terminal state. **The isolation was verified rather than assumed, and the hazard was live.** `actions/checkout` DID write the auto token into the local config — `git config --local http.https://gitea.com/.extraheader AUTHORIZATION: basic ***` appears in the log — and then removed it itself, because `persist-credentials: false` makes checkout clean up in its own step. Without a control there would have been checkout's write in the log and no way to show it was gone by push time: ``` in-run http.* local (none) · global (none) · credential.helper (none) NEGATIVE fabricated key rc=128 remote: Failed to authenticate user POSITIVE real key, same refs/probe namespace rc=0 lengths deploy 47, fabricated 44 — distinct, so the arms cannot be the same credential ``` ⚠️ **What this does NOT change:** the API-surface bound above stands unaltered. `write:repository` is still the narrowest category Gitea offers, so tier 3 bounds the push surface fully and the API surface only as far as the owning account's reach. **Tier 2 stays the default and tier 1 stays the default for anyone who sets nothing.** 📌 **Reusable, and cheaper than this test was:** a push to a ref outside `refs/heads/*` and `refs/tags/*` authorizes exactly like any push and triggers **no** workflow — measured, run count unchanged across a create and two deletes. `refs/probe/<name>` is a zero-cost write-capability probe. Measured by @quartermaster. Arms, controls and cleanup are his; the checkout-extraheader hazard was flagged before the run and proved live.