Connect your first repository

Outcome

Your repository is connected to prpl at a pinned revision. Customers finish this guide with their first harness build underway; wait-listed users finish with their repository saved and queued for the moment their account is upgraded.

Who can do it

• Customers (the scan.synth capability) can connect a repository and start the build.
• Organization members can do the same only on repositories where their owner granted scan capability (see Assign repository access and roles).
• Wait-listed users cannot launch anything yet — they use the pre-stage path at the end of this guide.

Before you begin

• GitHub access is connected, or you have a fine-grained read-only token ready to paste (Connect GitHub authentication).
• Know which branch, tag, or commit you want analyzed — prpl scans a pinned revision, not a moving branch.
• Only scan repositories you are authorized to analyze. Starting a build is cost-incurring work.

Steps — connect and start the first build

1. Open Attack surface in the top bar.
2. Select Scan repository (top right). If you have never scanned anything, the No scans yet card offers the same thing as Scan a repository.

3. The Scan a repository dialog opens. In the GitHub PAT row you will either see GitHub token on file ✓ (your stored credential) or a field to paste a fine-grained read-only token. Use a different token swaps in a fresh paste for this launch.
4. Select Load repos (Refresh repos when a token is on file). The Repository picker fills with the repositories your credential can see.
5. Pick your repository, then pick a revision from Branches or Tags. This fills Repository URL and Commit / ref for you — or paste the HTTPS URL and a sha, branch, or tag by hand.

6. Optionally expand Scope and scan settings: describe a Known vulnerability to focus the scan, add Scope notes (e.g. what is out of scope), choose an Agent profile, adjust the Recon task limit, or tick Hunt after build to run the scan automatically once the harness is ready.
7. Select Start scan.

prpl clones the pinned revision and takes you straight to the new job's plan page, where reconnaissance streams live and the harness build follows — that stage is covered in Prepare a repository environment.

Steps — wait-listed: pre-stage your repository

1. Open Attack surface. With GitHub access connected but launches still locked, you will see the Pre-stage your repository card.
2. Select Load my repositories and pick from the list, or paste the HTTPS URL into Repository URL.
3. Select Save repository for launch (Update saved repository on later edits).

Nothing runs and nothing is billed: the card shows Queued: with your repository and an awaiting upgrade tag. When your account is upgraded, the saved URL is pre-filled into the scan dialog so the first build is one click away.

Verify

• Customers: after Start scan you land on the build job's plan page (recon → plan approval → harness build). Back on Attack surface, the repository now appears in your inventory with its env/build/hunt counters.
• Wait-listed users: the Pre-stage your repository card shows "Repository saved." and your URL marked awaiting upgrade; the same URL also appears under BYOS defaults on the Account page.

Troubleshooting

• The picker says "Load a PAT first". No stored credential and nothing pasted — connect access first (guide) or paste a fine-grained token into the GitHub PAT field.
• "GitHub token was rejected or lacks repository metadata access." The token is expired or scoped to the wrong owner/repositories. Create a fresh fine-grained token with Contents: Read-only on the target repository.
• "GitHub repository was not found or is not visible to that token." The repository exists but your credential cannot see it — fix the token's Repository access selection on GitHub.
• "BYOS launches require a customer account; you're on the wait-list." Expected until a site administrator upgrades you. Use the pre-stage path above so launch is instant after upgrade.
• "you do not have scan access to this repository." You are an organization member without scan capability on this repository. Ask your organization owner to grant it (Assign repository access and roles).
• "runner dispatch failed". The scan infrastructure could not accept the job — nothing was started. Retry shortly; if it persists, contact your site administrator.

Next step

Prepare a repository environment — follow the harness build to its ready state. Related: Run a security scan and Add and scan more repositories.