Skip to content

book: the fine-grained permissions limen github check and fix need, per permission - #649

Merged
apostasie merged 1 commit into
mainfrom
claudio/20261110-github-permissions
Nov 10, 2026
Merged

apostasie merged 1 commit into
mainfrom
claudio/20261110-github-permissions

Conversation

@closer-claudio

Copy link
Copy Markdown
Contributor

book/github.md said administration read for most settings, secrets read for
the secret lists and administration write for an environment, and the design
document's auth table pointed at an issue for the rest. A human minting a
token for fix --org, or extending an App for the scheduled audit, had no
list to mint from.

The Authentication section now carries one table: scope, permission, the
level check needs and the level fix needs, and what each serves, derived
from the endpoints internal/github calls and GitHub's permission reference
for fine-grained tokens (the Actions policy, vulnerability alerts, code
scanning, teams and deploy keys under repository Administration; the
environment list under Actions and an environment's secrets under
Environments; the organization's policy, configurations and installations
under organization Administration; members and teams under Members; the
agents team's grant as repository Administration write with Members read).
Two things the reference made plain: the organization's fine-grained
token inventory is served to App tokens only, so under a fine-grained
personal access token that check is unverifiable; and gh's default scopes,
repo and read:org, read the repository rows and not the organization's
governed fields.

TestAuditEndpointFamilies holds the table to the code: the endpoint
families a full compliant audit reads, names and numbers reduced to
placeholders, against a list in the test, so a new read moves the table or
fails. The writes are each asserted by the fix test that performs them.

Closes #509

Sources read live: GitHub's permission reference for fine-grained tokens (https://docs.github.com/en/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens), the endpoint pages for GET /orgs/{org}, GET /users/{username}, the organization's personal access token list and the team repository grant, and gh's auth login manual for its default scopes. just lint and just test green.

@closer-claudio closer-claudio added the internal Changes nothing for a consumer; left out of release notes label Nov 10, 2026
apostasie
apostasie previously approved these changes Nov 10, 2026
…er permission

book/github.md said administration read for most settings, secrets read
for the secret lists and administration write for an environment, and
the design document's auth table pointed at an issue for the rest. A
human minting a token for `fix --org`, or extending an App for the
scheduled audit, had no list to mint from.

The Authentication section now carries one table: scope, permission, the
level `check` needs and the level `fix` needs, and what each serves,
derived from the endpoints internal/github calls and GitHub's permission
reference for fine-grained tokens (the Actions policy, vulnerability
alerts, code scanning, teams and deploy keys under repository
Administration; the environment list under Actions and an environment's
secrets under Environments; the organization's policy, configurations
and installations under organization Administration; members and teams
under Members; the agents team's grant as repository Administration
write with Members read). Two things the reference made plain: the
organization's fine-grained token inventory is served to App tokens
only, so under a fine-grained personal access token that check is
unverifiable; and gh's minimum scopes, repo, read:org and gist, read the
repository rows and not the organization's governed fields. A classic
token's scope is each endpoint's own, and the section says so with the
rows where it differs rather than naming one scope per row.

TestAuditEndpointFamilies holds the table to the code: the endpoint
families a full compliant audit reads, names and numbers reduced to
placeholders, against a list in the test, so a new read moves the table
or fails. The two reads off the compliant path are named in the test
and sit in a row the table already gives. The writes are each asserted
by the fix test that performs them.

Closes #509

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Signed-off-by: closer-claudio <claudio@farcloser.world>
@apostasie
apostasie merged commit 6cf84c3 into main Nov 10, 2026
14 checks passed
@apostasie
apostasie deleted the claudio/20261110-github-permissions branch November 10, 2026 09:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

internal Changes nothing for a consumer; left out of release notes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

github: the exact fine-grained permission set for limen github fix, in the book

2 participants