docs(auth): document fine-grained PAT permission for org publishing (+ pagination-cap test)#1435
Merged
Merged
Conversation
The org-namespace guidance only mentioned the classic `read:org` scope, so a user who mints a fine-grained PAT (GitHub's recommended token type) gets their personal namespace only, with no hint why org publishing silently doesn't work. Document both token types: classic PATs need `read:org`; fine-grained PATs need "Organization permissions → Members → Read-only" (the equivalent), and are bound to a single resource owner. Also note `read:user` is not required. Verified against staging: a fine-grained PAT without Members:read is granted only the personal namespace; after adding it, the org (Owner role) namespace is granted. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…omment - Add a test that the org-memberships pagination fails closed (no token issued) when every page is full and the loop hits maxOrgMembershipPages, rather than returning a possibly-truncated org grant. - Qualify the X-GitHub-SSO comment: it's a best-effort defensive check. We have not confirmed the memberships list endpoint emits X-GitHub-SSO on SSO enforcement (it may just omit the org); the check is safe either way but is not a proven guarantee that every SSO-blocked Owner is caught. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up to #1383, surfaced while validating that change end-to-end against staging.
Why
#1383 hardened org-namespace publishing to require Owner (
admin) role, read viaGET /user/memberships/orgs. Validating on staging revealed a gap: the docs only mention the classicread:orgscope, but a fine-grained PAT (GitHub's recommended token type) needs a different permission to expose org membership. Without it, GitHub returns no org memberships for the token, so the exchange silently grants only the personal namespace — with no hint why org publishing "doesn't work."This is not a code bug (the behavior is fail-closed and correct given GitHub's response); it's a documentation/UX gap.
What
authentication.mdx,github-actions.mdx): spell out both token types —read:orgscoperead:useris not required.github_at_test.go): cover themaxOrgMembershipPagespagination cap — when every page is full, the exchange fails closed (no token) rather than returning a possibly-truncated org grant. This path was previously untested.github_at.go): qualify theX-GitHub-SSO403 check as best-effort — we have not confirmed the memberships list endpoint emits that header on SSO enforcement (it may just omit the org). The check is safe either way, but the comment no longer overstates it as a guarantee.Verification (live, against staging)
Confirmed by exchanging real tokens for
rdimitrovonstaging.registry.modelcontextprotocol.io:read:orgPAT across 16 real org memberships → the JWT granted exactly the 8 admin orgs + personal namespace, and zero of the 8 member orgs (incl.stacklok,modelcontextprotocol) — the core fix(auth): grant org namespace only to org Owners, not all members #1383 behavior, working.No runtime behavior change here beyond the added test; the docs and comment are the substance.