sec(mint-scope): the gate that writes nothing stops minting write on everything

[LukasWodka]

What

fr-gate.yml performs zero mutations. Measured, not assumed — no GraphQL mutation, no gh pr/gh issue write, no REST POST/PATCH/PUT/DELETE, no git push. It reads, and its only output is its own check conclusion.

It was nevertheless minting the App's entire permission set — contents:write, issues:write, organization_projects:write, administration:read — across every repo the installation covers.

A pure reader holding org-wide write is the sharpest mismatch of the four this ticket found.

The scopes come from the file's own comment

The workflow already documented exactly what it touches, which is why this could be checked rather than guessed:

It reads commits/{sha}/pulls, compare/{base}...{head} and the ProjectV2 graphql — every one covered by permissions the App already holds. It never writes a card, a label or a comment; the gate's only output is its own conclusion.

call	scope
commits/{sha}/pulls	contents: read + pull-requests: read
compare/{base}...{head}	contents: read
ProjectV2 graphql (pullRequest.projectItems → fieldValueByName("Status"))	organization-projects: read

permission-contents: readpermission-pull-requests: readpermission-organization-projects: read

actions/checkout is not on this token — it takes the job's default GITHUB_TOKEN — so the checkout needs nothing from here either.

If the scope is short

The gate fails closed and blocks promotions. That is loud, immediate, and recoverable with the skip-fr-gate label. It is also the failure direction this gate explicitly chose for itself:

a fallback would let a broken App path keep working silently, and this gate blocking wrongly is far better than it passing wrongly

No signal until the hop — stated plainly

Callers pin tracebloc/.github/.github/workflows/fr-gate.yml@main. So every promotion keeps using main's unscoped copy until develop → staging → main lands, and a green run on this PR proves nothing about the narrowed scope. The first real exercise is the first promotion after that hop.

This is the same caveat as #349, and the two are deliberately paired into the same hop: an fr-gate failure (promotions blocked) and a set-pr-status failure (cards frozen) look nothing alike, so promoting them together stays diagnosable.

Not closing the ticket

Two of four. Remaining: kanban-reconcile.yml (three board writes, weekly cron) and standards-sync.yml (report-only on most triggers but mints Contents: RW for the create-prs dispatch mode — the largest mismatch left, and the one whose risky mode cannot be rehearsed without opening 19 real PRs).

Test plan

• make lint — clean
• make selftests — 28 passed, 0 failed
• actionlint — clean
• make mint-scope — 3 unscoped / 3 exempted / 0 findings
• Live: not exercisable from this PR. See above.

Part of tracebloc/backend#2157

---

Note

Medium Risk
Narrows a fleet-wide required check’s App token from org-wide write to read-only; if scopes are wrong, promotions fail closed until skip-fr-gate or a fix, which is intentional but operationally sensitive.

Overview
The FR gate reusable workflow no longer mints the release-train GitHub App’s full installation token. The create-github-app-token step now requests only contents: read, pull-requests: read, and organization-projects: read, aligned with its three read paths (commits/{sha}/pulls, compare, ProjectV2 GraphQL). Checkout still uses the default GITHUB_TOKEN, not this mint.

scripts/mint-scope.py removes fr-gate.yml from the temporary EXEMPT list and updates the burn-down notes so only standards-sync.yml remains exempt from the explicit permission-* requirement.

^{Reviewed by Cursor Bugbot for commit 9d642d9. Bugbot is set up for automated code reviews on this repo. Configure here.}

[saadqbal]

Checked the load-bearing claim rather than taking it: grepped all 542 lines of fr-gate.yml for any mutation, gh write subcommand, non-GET REST method, or git push — nothing. A pure reader holding org-wide contents:write was the right one to call the sharpest mismatch of the four.

Deriving the three scopes from the calls, and noting actions/checkout rides the job's default GITHUB_TOKEN rather than this one, is what makes it reviewable. 👍

[saadqbal]

Re-approving. My earlier stamp was dismissed by the develop merge, and I checked what actually moved rather than assuming a merge changed nothing: d6e5b49b/2017a1c1/bdd979cd came in from develop, and the PR's own diff picked up scripts/mint-scope.py — the fr-gate.ymlEXEMPT row removal plus the prose rewrite that goes with it. Both correct; the row has to go in the same PR that scopes the workflow, or the staleness guard fires.

One thing for the pair, not for this PR alone.#355 rewrites the same comment block and the same dict, and the two are mirror images: this one says "the ONE left … standards-sync", #355 says "the ONE left … fr-gate". Each is true only while the other is open. So two consequences worth knowing before you merge either:

• Whichever lands second hits a textual conflict here. If it's resolved by keeping the other's EXEMPT row, mint-scope fails on stale — which is the right direction to fail, and it's caught.
• After both land, EXEMPT is {} and the surviving prose still claims one exemption remains. Nothing catches that: the guard checks for rows that no longer mint, not for prose describing rows that aren't there. Worth having the second PR drop the "the ONE left" block to "none left, and here is what the four were" as part of its conflict resolution.

The EXEMPTIONS ARE TEMPORARY, AND STALENESS IS A FINDING framing is what makes this whole burn-down legible — it'd be a shame for the last step to leave the narrative one PR out of date. 👍

[aptracebloc]

Reviewed at high effort — correct and safe. Approving.

The security substance is right: the mint narrows from the App's full org-wide set (contents:write, issues:write, organization_projects:write, administration:read) down to exactly contents:read + pull-requests:read + organization-projects:read, and those three map one-to-one to the workflow's only token consumers — commits/{sha}/pulls, compare/{base}...{head}, and the ProjectV2 Status GraphQL read. actions/checkout rides the default GITHUB_TOKEN, so no write scope is needed anywhere. It's neither too narrow (nothing else touches the minted token) nor still-broad (no writeable scope requested), and it fails closed — a bad permission key would 422 at mint. Dropping fr-gate from EXEMPT is required and consistent with #349.

Runtime proof it actually works: the gate check (this very fr-gate workflow) passed on head 25bb5874, so the narrowed token minted and completed its three calls — the change is exercised, not just static.

One non-blocking nit worth a one-line follow-up: the mint-scope.py docstring prose (~L120–122) still reads "six became four" / "The four left" and names fr-gate as one of the still-deferred exemptions with the "required check fleet-wide, needs its own window" rationale — but this PR removes fr-gate from EXEMPT, leaving three. The tally now contradicts the list it sits above (the exact hardcoded-count-above-its-list pattern this file elsewhere warns against). Doesn't gate approval.

— drafted with Claude Code