GitHub authentication and permissions reference

Outcome

You can name every GitHub credential prpl uses, say exactly what each one can and cannot do, and audit or revoke each of them on both sides.

Who can do it

Reading this reference: everyone — it is public.
Storing or revoking a repository credential: wait-listed and customer accounts (the repo.connect capability). Organization members don't hold their own repository credential; the owner's access covers granted repositories.
Installing or configuring the GitHub App: only the App's owning account (see the install guide).

Before you begin

Keep the core distinction in mind: identity (who you are — used at sign-in, never stored) is separate from repository clone authorization (what prpl may read — stored, encrypted, revocable). No sign-in ever grants code access, and no code grant is ever required to sign in.

The grants, side by side

Grant	Where it happens	Scopes / permissions	Stored by prpl?	What it's used for	Least-privilege alternative
Sign-in with GitHub (identity OAuth)	Sign in to prpl page → Sign in with GitHub	`read:user`, `user:email` — identity only, no repository access	No — the token is used once to identify you and discarded; only your GitHub login and email are kept	Creating your account and session	Already minimal; invited members can skip GitHub entirely via their invitation link
Fine-grained personal access token (recommended)	Created on GitHub; pasted into Account → Use a scoped token → Save token	`Contents: Read-only` on the selected repository (+ automatic `Metadata: Read-only`)	Yes — encrypted at rest, shown as scope `byos-pat`, never redisplayed	Listing your repositories/refs in the pickers and cloning the pinned revision for analysis	This is the least-privilege option: one repository, read-only, with an expiration
Connect with GitHub (repository OAuth grant)	Account → Connect with GitHub → Connect	`repo` (plus `read:user`, `user:email`) — GitHub's classic scope, worded as full control of private repositories; classic OAuth has no read-only scope	Yes — encrypted at rest, with the granted scopes recorded, never redisplayed	Same as the token above, but across every repository your GitHub account can reach	Use a fine-grained token instead; prpl only reads even under this grant
Organization invitation (no GitHub credential)	Email link → Join your organization → Accept invitation	None on GitHub — a single-use prpl credential; only its hash is stored, links expire after 72 hours	Hash only; the raw link is never stored and cannot be replayed after use, expiry, or revocation	Creating a member account and session without a GitHub login	Already minimal; the member sees only repositories the owner grants
prpl Defender GitHub App (`prpl-private`)	GitHub install flow at `github.com/apps/prpl-private/installations/new`	The permission set GitHub displays on the install screen; review it there. Installation is restricted to the App's owning account because the App is private	Installation state lives on GitHub, not in prpl	Organization-level installation on chosen repositories; it does not replace the clone credentials above today	Install with Only select repositories rather than all repositories

Storage details for the two stored credentials: they live encrypted in prpl's auth database keyed to your user, are decrypted only when a scan needs to list or clone your repository, and are never rendered back to any page or log. One credential is stored per account — saving a new one replaces the old.

Steps — audit what prpl holds

Open your profile menu → Settings → GitHub repository access. A green Connected. panel shows the stored credential's scope (byos-pat for a pasted token, OAuth scopes otherwise) and when it was stored. No panel means prpl holds no repository credential for you.
The Connected panel in GitHub repository access with the token masked, calling out the scope and stored-date line. No secret values may appear.
Cross-check on GitHub: Settings → Developer settings → Fine-grained tokens for pasted tokens, and Settings → Applications → Authorized OAuth Apps for the Connect grant.
To rotate, generate a fresh fine-grained token and Save token — the stored credential is replaced. To remove, select Revoke on the Connected panel, then revoke the credential on GitHub too (prpl's copy being gone does not invalidate GitHub's original).

Verify

The scope shown on the Connected. panel matches what you intended to grant — byos-pat if you followed the recommended path.
After Revoke, the Account page shows "Stored GitHub token cleared." and the Connected panel disappears; the scan dialog on Attack surface goes back to asking for a token.

Troubleshooting

Signed in fine, but repository loading fails. Identity and clone authorization are different grants — being signed in proves nothing about code access. Store a repository credential: Connect GitHub authentication.
prpl still shows Connected after you revoked the credential on GitHub. The panel reflects that prpl holds a stored copy, not that GitHub still honors it — scans will fail with a rejected-token error. Select Revoke in prpl and store a fresh token.
The OAuth grant looks alarming in GitHub's Authorized OAuth Apps. The classic repo scope is broad by GitHub's design. If that is more than you want outstanding, revoke it there, then store a fine-grained token instead.
A fine-grained token expired. Scans start failing at clone. Generate a replacement (same settings, new expiration) and Save token.

Next step

Connect GitHub authentication to act on this reference, or continue to Roles and permissions for what your account may do once access is connected. App installation questions: Install the private prpl Defender GitHub App.

Last verified against commit c0bf54d on 2026-07-10 · capture scenario: github-auth-reference