Prepare a repository environment

Outcome

You will have a ready repository environment — an isolated, runnable copy of your repository, built from one pinned commit — and you will know how to approve the build plan that gates it. prpl calls this build a Harness build: it maps your code (recon), proposes a build plan for your approval, and then assembles the environment.

Who can do it

• Customer accounts can build environments for repositories they connect.
• Organization members need two things from their organization owner: the repository granted to them (Access) and a capability that includes “Build the analysis harness for a repo” — held via the org-wide seat grants or the Repo owner role on that repository. See Roles and permissions.
• Waitlist accounts can browse and pre-stage a repository but cannot start builds until upgraded.
• Site admins can build against any repository.

Before you begin

• GitHub access is connected — an OAuth grant or a fine-grained read-only token (see Connect GitHub authentication).
• You know which commit, branch, or tag to build. Environment builds pin an exact revision; a moving branch tip is resolved to a commit at build time.
• Only scan repositories you are authorized to analyze — the scan form reminds you of this, and it is a condition of use.
• Builds incur cost. An interactive build pauses for your approval before any environment is assembled, so nothing is spent on the build phase until you approve.

Steps

1. Open Attack surface (/byos) from the top navigation.
2. Click + Scan repository (on a repository you already scanned, open the repository and click + Scan this repository instead).
3. In the Scan a repository dialog, choose the repository and fill Commit / ref. Full details of this form are in Add and scan more repositories.
4. Optionally expand Scope and scan settings to add a Known vulnerability description, Scope notes, an Agent profile, a Recon task limit, or tick Hunt after build.
5. Click Start scan. You land on the build's plan page, which shows a four-step pipeline: Recon → Plan review → Harness build → Result.
6. Wait for Recon to finish mapping the codebase — subsystems, entry points, and trust boundaries appear as they are discovered.
7. At Plan review the build pauses on a human gate: “Nothing builds until you approve.” Read the proposed Build specification; you may expand plan json — edit before approving to adjust it. Then click Approve & build (or Cancel to abandon the run).

8. The Harness build phase runs unattended. The outputs ledger fills in as files are produced, and the live console streams the build steps.

9. When the build completes, the Result step shows Harness ready with a Launch hunt call to action.

Verify

• On the repository page, the Environments & hunts tab lists the new environment with a green ready badge and an inline Launch hunt control.

• The Build jobs tab shows the build job with status ready and the environment name it produced.
• The repository header counters (envs, builds) have increased.

Troubleshooting

The build seems stalled and the repository shows “Action required”

The build is paused at the human review gate. The repository page shows an amber banner — “… paused, waiting for you to review & approve the plan before the harness is built. Hunts can't run until then.” Click Review build plan and approve or cancel. The same items appear in the Needs your decision panel on the Attack surface landing page with a Review & approve plan button.

The build finished as “failed”

The Build jobs row shows a failed badge with a short reason, and the plan page's Result step reads Build failed. Common causes: the commit or ref does not exist, the repository cannot be cloned with the stored credentials, or the project cannot be assembled at that revision. Open the job to read the reason and the build console, correct the input (for example pick a different ref or reconnect your token — see Connect GitHub authentication), then start a new scan. Failed builds can be archived from the repository view (Archive scans, findings, and history).

The environment row says “Not ready to hunt”

The environment's metadata exists but the runnable harness is not built yet — either the build is still executing or it stopped before producing a runnable target. Wait for the build to finish, or check the Build jobs tab for a paused or failed build to act on.

An environment name link asks you to log in or returns “not found”

The environment detail page is currently operator-only. Monitor your environments from the repository's tabs and from Jobs instead — everything you need (status, hunts, findings) is available there.

Next steps

Run your first hunt against the ready environment: Run a security scan. To keep the environment fresh on a cadence, see Schedule recurring scans.