`pin` job cannot push its bump branch — the broker's `front-desk` entry never requested `contents`, and the scope assertion did not check for it

[bdelanghe]

The pin job in org-defaults.yml cannot complete its bump. It fails on every push to main that changes a fetched .claude/ file, which means the pin never self-heals and main sits red on schema until someone bumps it by hand (as #86 does for #84).

The failure

Run 30703899767, on the merge of #84:

Switched to a new branch 'bootstrap-pin/bump'
[bootstrap-pin/bump 9c40f1c] chore(bootstrap): pin a7cb962f8920 and re-record digests
 1 file changed, 3 insertions(+), 3 deletions(-)
remote: Permission to bounded-systems/.github.git denied to bounded-systems-front-desk[bot].
fatal: unable to access 'https://github.com/bounded-systems/.github.git/': The requested URL returned error: 403
##[error]Process completed with exit code 128

The token minted fine and the generator did its work. The front-desk App installation is missing contents: write on this repo, so git push -f origin bootstrap-pin/bump 403s.

Two separate things to fix

1. The grant (needs a human)

Give the front-desk App installation contents: write on bounded-systems/.github, or point the job at an identity that has it.

Worth confirming which of the two wrangler.jsonc cases this is, since the repo already records the reading: mint succeeded + the call 403'd means the broker did not ask for the scope, and that is fixable in the registry. A missing installation grant would have failed the mint outright, which it did not. So this looks like the broker-side case.

2. The assertion is one scope short (fixable here)

The job has a step named "The minted token can actually open a PR" which asserts pull_requests: write before doing the work. Its comment explains exactly why:

Assert the scope BEFORE doing the work. […] until now nothing consumed it, so a missing scope surfaced only as a 403 at gh pr create, after the branch had already been pushed.

The same argument applies one step earlier and was not extended to it. Pushing the branch needs contents: write, that scope is never asserted, and so the failure arrived as a bare 403 and exit 128 — which killed the script before any of the carefully written ::error title=pin: branch pushed, PR not opened:: annotations below could run. The job comments predict a failure mode ("branch pushed, PR not opened") that cannot occur, because the branch cannot be pushed at all.

Adding contents to that check makes the next occurrence name itself instead of costing a log dig.

Impact while it stands

The pin is the fallback path's trust anchor, so this is invisible to anyone with .github attached — the attached checkout always wins — and only bites a session that does not have it. That is the same "works for me, fails for a session without .github" shape bootstrap-pin.test.mjs was written about after #71 and #72, now recurring one layer out: the gate correctly detects the stale pin, and the thing meant to act on that detection is broken.

Related: #85, on the setup-script field. Different mechanism, same theme — the automation around the bootstrap is less load-bearing than it reads.

[bdelanghe]

Which App

Broker registry key (GH_APPS)	front-desk — what the three workflows pass as app:
GitHub identity	bounded-systems-front-desk[bot] — the name in the 403
Needs	contents: write on bounded-systems/.github

Three callers, all naming the same app: org-defaults.yml (the pin job), registry-graph.yml, and front-desk-add.yml.

It has never worked, and a second workflow has the same latent bug

registry-graph.yml does the same push with the same App, and its recent scheduled runs all report success — which looks like evidence the grant is fine. It isn't. That job early-exits on [ -z "$(git status --porcelain)" ] && { echo "in sync"; exit 0; }, so a success only means the registry hadn't changed.

The decisive check is whether either job's branch ever landed. Neither exists:

$ git ls-remote --heads origin | grep -E 'bootstrap-pin/bump|registry-graph/'
(no output)

So this is not a regression. bounded-systems-front-desk[bot] has never pushed a branch here, and #84's merge was simply the first time anything needed it to. registry-graph.yml will 403 identically the first time the registry actually changes — it is not currently broken only because it has never had work to do.

That also revises the note in the body about which of wrangler.jsonc's two cases this is. "The broker did not ask for the scope" assumed the grant had been working and something regressed; with the grant never exercised, an installation that simply lacks contents: write is equally consistent. Whoever fixes it should check both rather than trusting the earlier reading.

Where the broker source is not

front-desk-add.yml points at infra/cloudflare/broker, but in bdelanghe/infra today that path is a placeholder:

infra/cloudflare/
└── .gitkeep

infra is three commits (scaffold: infra skeleton (zones + structure; stack TBD)), so the comment describes where the broker is meant to live, not where it is. Anyone picking this up needs to find the deployed cf-token-broker Worker's actual repo first.

---

Generated by Claude Code

[bdelanghe]

Resolved: it is the installation, and it was specified that way

The earlier comment left both cases live — broker not requesting the scope, or the installation lacking it. .github-private → docs/handoffs/front-desk-app-credentials.md settles it. The App's documented grant list, in the step that stood it up:

App. Create the dedicated Front Desk App (Org Projects: read+write; repo Issues/PRs/Contents: read), install on the org → All repositories.

Contents: read. So the push was never possible, and nothing regressed — the App is doing exactly what it was installed to do. Every symptom in this issue follows from that one line, and the "never worked" evidence in the previous comment is the confirmation rather than the discovery.

That also retires my original reading of wrangler.jsonc's discriminator. I took mint-succeeded-plus-later-403 to mean the broker had not asked for the scope, which assumed the grant existed to be asked for. It did not.

What this changes about the fix

Not simply "grant contents: write". That widens a door that was deliberately narrow — the App holds org-wide Projects read+write and is installed on all repositories, so broadening its repo write surface is a real increase in blast radius, not a formality.

Two options, and this is a judgement call for whoever owns the App rather than something to pick by default:

1. Widen this App to Contents: write. Simplest; one setting. Costs the narrowness on every repo it is installed on.
2. A separate push identity scoped to the repos that actually need branch pushes (.github today). Preserves the narrow grant, at the cost of a second App and a second broker registry entry.

Option 2 is more in keeping with the org's posture — the door is the unit of bounded authority, and this is one door being asked to do two jobs. But it is more moving parts for a bump branch, so I am not asserting it is right.

Either way, #93's preflight and #92's probe are unaffected and still worth doing: they are what turns the next instance into a named failure at mint time, and a scheduled red, instead of a month of green from a job that did nothing.

Recorded in the handoff itself via .github-private#270, so the next person to read the credentials doc finds it there rather than here.

---

Generated by Claude Code

[bdelanghe]

Decision: separate push identity. Do not widen front-desk.

The org's own doctrine decides this one; recording the derivation so it can be challenged rather than re-litigated.

Why not option 1. A GitHub App's repository permissions are declared per-App, not per-repo — Contents: write on front-desk would apply everywhere it is installed, and it is installed org-wide (All repositories, per the credentials handoff) because its actual job needs org-wide reads. Narrowing the installation instead is not available: the sync genuinely needs every repo. So option 1 converts "one workflow needs to push one bump branch in one repo" into "the board-sync identity can write contents to every repo in the org". The org context's first sentence — the door is the unit of bounded authority — is a decision procedure here, and it says no: this is one door being asked to do two jobs, and the fix for that is a second door, not a wider one.

Blast-radius check, both directions. Widening front-desk: a compromise of the broker entry or App key becomes org-wide write. Separate identity: the same compromise is scoped to .github's contents — and main there is protected with a required check, so a hostile push lands on a branch, not on the trunk. The asymmetry is decisive on its own.

Spec

App	front-desk-porter (hotel naming — carries things; concierge stays reserved). Name is cosmetic; the scoping is not.
Repo permissions	Contents: write, Pull requests: write. Nothing else — no Issues, no Projects.
Installation	Only select repositories: .github. Extend per-repo if another repo ever needs bump pushes.
Broker	New GH_APPS entry front-desk-porter, same OIDC pins as front-desk.
Callers	org-defaults.yml (pin job), registry-graph.yml → app: front-desk-porter; add require: contents, pull_requests when #93 lands. front-desk-add.yml stays on front-desk — it needs Projects, not pushes.
front-desk	Unchanged. Contents: read was correct all along; this issue turns out to be a missing second identity, not a wrong grant.

Human steps (Owner): create the App, install on .github only, register it in the broker. Automatable once the broker repo is located: the registry entry and the two workflow changes — I'll take those with #93. Until then the manual pin bump after any .claude/-touching PR remains the standing cost (two on 2026-08-01).

Sequencing with #92: the probe should exercise front-desk-porter's push, and can double as its acceptance test — land the probe red, watch it go green when the App is installed.

---

Generated by Claude Code