flux bootstrap github fails: 403 Resource not accessible by personal access token

Bootstrap got far enough to push manifests, then failed creating the deploy key - the token lacks the Administration permission that governs deploy keys. For fine-grained tokens add Administration read/write (plus Contents read/write); for classic tokens use the full repo scope. Changing a fine-grained token's permissions revokes org approval, so get it re-approved, then re-run the identical bootstrap - it is idempotent and resumes where it stopped.

The error

POST https://api.github.com/repos/[org]/[repo]/keys: 403 Resource not accessible by personal access token

What to do

1. Fix the token - fine-grained needs Administration read/write + Contents read/write (classic: repo scope). Get org re-approval if permissions changed.

Expected: Token approved with the new scopes.

1. Re-export and re-run the identical command:

export GITHUB_TOKEN [your value] token]
flux bootstrap github --owner=[org] --repository=[repo] --branch=main --path=[path]

Expected: Bootstrap resumes and completes.

1. Verify:

flux check
flux get sources git -A

Expected: All checks pass; flux-system source Ready.

When this applies

• the exact 403 Resource not accessible by personal access token during bootstrap
• fine-grained PATs missing Administration scope
• first bootstrap on an org repo

When it does NOT apply

• ssh: handshake failed later in bootstrap (deploy key created, SSH broken - different fix)
• 422 deploy keys disabled (org setting, not token scope)

Works with

flux CLI 2.x; flux bootstrap github

GET .../keys: 403 on re-bootstrap

Same missing scope, hit while listing keys. Same token fix.

Why it happens

Flux installs a deploy key via the GitHub API, which is an administration action. Contents write lets it push manifests but says nothing about keys - GitHub's permission model splits them, and the 403 names the token as the problem.

Edge cases

• --token-auth dodges the permission by storing the PAT in-cluster, but the PAT then expires silently and sync stops - prefer deploy keys.
• Bootstrap is idempotent: never start over with a fresh repo, just re-run.

Resolved from

gh:five-borough-fedi-project/masto.nyc-docean (flux-bootstrap notes) - https://github.com/five-borough-fedi-project/masto.nyc-docean/blob/HEAD/docs/flux-bootstrap.md