Connect GitHub authentication

Outcome

prpl holds a credential that lets it clone the repository you want analyzed. Your Account page shows a green Connected panel, and the scan form on Attack surface shows GitHub token on file ✓.

Who can do it

• Wait-listed and customer accounts (the repo.connect capability). Wait-listed users can and should do this step early — it is pre-configuration, not spend.
• Organization members do not connect their own repository credential: they work in repositories their owner granted, and the owner's scans supply the access. Members can skip this guide.

Before you begin

• Be signed in (Sign in and set up your account).
• Pick your method:
  • Use a scoped token (recommended) — a GitHub fine-grained personal access token limited to one repository, read-only. Least privilege; takes a minute.
  • Connect with GitHub (optional) — one-click OAuth that works across all your repositories, but classic OAuth has no read-only scope, so GitHub will show a broad repo "full control of private repositories" consent screen. prpl only reads, but the token could do more — that is why the scoped token is recommended.
• Only connect repositories you are authorized to have analyzed.

Steps — Option A: use a scoped token (recommended)

1. Open your profile menu → Settings, and find the GitHub repository access section. Under Use a scoped token (tagged recommended) prpl shows the same walkthrough as below.
2. On GitHub, open Settings → Developer settings → Fine-grained tokens → Generate new token (linked from step 1 of the walkthrough).
3. Token name — e.g. prpl-byos-<repo>, and set an expiration (90 days is a good default).
4. Resource owner — pick the account or organization that owns the repository you want analyzed.
5. Repository access — choose Only select repositories and select the one repository. Don't grant "All repositories".
6. Permissions → Repository permissions — set Contents to Read-only. That is the only permission needed; Metadata: Read-only is added automatically. Leave everything else as "No access".
7. Generate token and copy the github_pat_… value — GitHub shows it once.
8. Back on the prpl Account page, paste it into the Paste your token field and select Save token. The token is encrypted at rest and never displayed again.

Steps — Option B: connect with GitHub (OAuth)

1. On the Account page under GitHub repository access, find the Connect with GitHub card (marked optional — it is never required for prpl login).
2. Select Connect (it reads Reconnect if a token is already stored).

3. Approve GitHub's consent screen. It requests the broad repo scope — GitHub words this as full control of private repositories; classic OAuth simply has no read-only option.
4. You are returned to prpl with "GitHub access token saved." — the OAuth token is now stored (encrypted) as your durable clone credential.

Both options are also offered directly on Attack surface the first time you arrive without any access set up, on the Connect a repository to get started card.

Rotation and revocation

• Replace: saving a new token (either option) overwrites the stored one.
• Revoke in prpl: on the Account page's Connected panel, select Revoke to delete the stored token. The empty paste form deliberately refuses to clear a token — Revoke is the only way to remove it.
• Revoke at the source: prpl's copy is only a copy. Also revoke the credential on GitHub — the fine-grained token under Settings → Developer settings → Fine-grained tokens, or the OAuth grant under Settings → Applications → Authorized OAuth Apps.

Verify

• The GitHub repository access section now shows a green panel: Connected. with the credential's scope (for a pasted token: byos-pat; for OAuth: the granted scopes) and when it was stored.
• On Attack surface, opening the scan dialog shows GitHub token on file ✓, and Load repos lists the repositories your credential can see.

Troubleshooting

• "GitHub token was rejected or lacks repository metadata access" when loading repositories. The token is expired, was revoked on GitHub, has the wrong Resource owner, or is missing Contents: Read-only. Generate a fresh fine-grained token against the correct owner and save it again.
• Your repository doesn't appear in the picker. A fine-grained token only sees the repositories selected at creation. Edit the token on GitHub (or create a new one) with the right repository selected, then save it again.
• "empty token" when saving. The paste field was blank — pasting nothing never clears a stored token. Paste the full github_pat_… value, or use Revoke if removal is what you wanted.
• "token storage not configured" / "GitHub OAuth not configured". The deployment is missing its auth configuration; contact your site administrator.
• The OAuth consent screen asks for more than you want to grant. That is expected for Option B (classic OAuth has no read-only scope). Cancel on GitHub's page and use Option A instead — nothing is stored unless you complete the flow.

Next step

Connect your first repository — pick the repository and revision and start your first build. Reference: GitHub authentication and permissions reference.