# Repository scans

Scan a whole repository at one commit with `proofline scan`, outside a pull request and within a credit budget you set. The results stay in Proofline.

## What a scan analyzes today

Proofline cannot analyze a scan's files yet. An accepted scan fixes its commit, divides the repository's files into partitions and reads each partition at that commit, but no partition is analyzed. A scan of a repository with files therefore ends without a complete result and records no findings. Request one today to try the request, the receipt and your access; it does not assess the code.

What an accepted scan does establish is narrow. Its resolution receipt records the one commit that the ref or SHA resolved to when the request arrived, and every repeat of the request returns that same commit. A non-null `review_id` shows that Proofline accepted the scan and recorded its work for that commit. A partition that was read but not analyzed shows only that its files could be read at that commit: it adds no finding and no coverage.

The scan's review records the gap in its status. It ends `FAILED` when Proofline listed the whole tree but analyzed none of it, and `INCOMPLETE` when the tree could not be listed in full. A review in either status has no findings, and that absence is not a result. `proofline scan` prints the status and `Code-only: incomplete (CODE_ASSESSMENT_UNAVAILABLE)`, then exits 2, and the console's review page shows **Scan analysis unavailable**.

Three gaps can leave you without a result, and each means something different:

- No scan started: GitHub could not resolve the ref or commit, the receipt's `review_id` is null, nothing was spent and there is no review to read.
- A partition the budget did not reach is recorded as not scanned because the scan's budget was spent before it started.
- A partition that was read but not analyzed is today's limit, and it applies to every partition of every accepted scan.

The limit concerns the scans this page requests. [Repository audits](/help/repository-audits/) are a separate request with their own report, and a scan checks no environment, whatever its status.

## Before you scan

A scan spends credits from an on-demand limit that an administrator sets in the organization's review settings. The limit starts at 0, which refuses every scan, so ask an administrator to raise it first. Reviewing must be enabled for the repository.

The token needs the `scans:request` scope, and you need write access to the repository on GitHub. Proofline checks that access with GitHub on every request, including a repeated one; the scope alone grants nothing. The default `proofline login` omits the scope. `--scope` replaces the default scopes, so name every scope you want:

```sh
proofline login --scope reviews:read --scope findings:read --scope reviews:request --scope scans:request
```

### A sign-in for scans only

A sign-in can hold `scans:request` alone, for someone who should start scans but not read their results. Approve it for only the repositories it should scan:

```sh
proofline login --scope scans:request
```

Such a sign-in can find its repository and request a scan. It cannot read reviews or findings, so it never sees the scan's result. `proofline status` checks it against the scan route and prints `server: accepted the token for scans`. Someone whose sign-in includes `reviews:read` reads the result from the scan's link.

## Run a scan

From a checkout of the repository, scan the commit a branch points to:

```sh
proofline scan --ref main --budget 200
```

GitHub resolves the ref once, when the request arrives, and the scan records that commit. To scan an exact commit, name its full SHA with `--commit` instead:

```sh
proofline scan --commit 4f6c2a9e8b7d1c3e5f0a2b4c6d8e0f1a3b5c7d9e --budget 200
```

Give exactly one of `--ref` and `--commit`. `--commit` takes a full 40-character SHA and refuses a branch name.

`--budget` is required and has no default. It is the most credits the whole scan may spend, and it cannot exceed the organization's on-demand limit. The CLI reads the repository from the checkout's `origin` remote; `--repo owner/name` names another one, and `--remote` names another remote.

When the sign-in can read reviews, the command waits up to 20 minutes for the scan's review and prints it as `proofline review` does. `--timeout` sets the minutes to wait, `--no-wait` prints the scan's console link without waiting, and `--json` prints JSON.

## What the command prints

The command prints the request ID first, then one of three outcomes. Only the first can show a finished scan.

**The command waits for the result.** It prints `Started a scan, resolution …`, waits for the scan's review and prints it. It exits 0 for a complete result, and 2 for an incomplete result or a scan that has not finished at the timeout. Because no partition is analyzed today, a scan of a repository with files ends as this one does, with exit 2:

```text
Requesting a scan of acme/web at main with a budget of 200 credits (request 0199b000-0000-7000-8000-0000000000bb).
Started a scan, resolution 0199b000-0000-7000-8000-0000000000c1.
acme/web at 4f6c2a9e8b7d: FAILED
https://proofline.sh/orgs/by-id/0199b000-0000-7000-8000-000000000001/reviews/0199b000-0000-7000-8000-0000000000c2
Code-only: incomplete (CODE_ASSESSMENT_UNAVAILABLE)
The review did not finish, so it has no complete result.
```

The commit after `at` is the one the receipt recorded. `FAILED` here means that Proofline read the tree and analyzed none of it.

**The scan started, but this sign-in cannot read its result.** A sign-in without `reviews:read` stops after the scan is accepted:

```text
Requesting a scan of acme/web at main with a budget of 200 credits (request 0199b000-0000-7000-8000-0000000000bb).
Started a scan, resolution 0199b000-0000-7000-8000-0000000000c1.
This sign-in cannot read reviews, so the CLI does not wait for the result; open the scan's link instead.
https://proofline.sh/orgs/by-id/0199b000-0000-7000-8000-000000000001/reviews/0199b000-0000-7000-8000-0000000000c2
```

The link is the only line on standard output. The command exits 0, as `--no-wait` does, because the scan was accepted; that exit says nothing about its result, which may still be running. Read the result from the link, or with `proofline findings --review ID --wait` on a sign-in that includes `reviews:read`.

**No scan started.** When GitHub cannot resolve the ref or commit, the command says that no scan started and nothing was spent, names the resolution and exits 1. There is no review and no link.

A scan's results stay in the CLI, the API and the Proofline console, and are never posted to GitHub. A scan reviews code only: it does not check an environment, and its result states nothing about one. Read a scan's status before its finding count. A scan that ends `FAILED` or `INCOMPLETE` today analyzed nothing, so its empty finding list says nothing about the code. Even a complete scan with no findings means only that no supported finding emerged from the evidence available to it. It does not establish that the repository has no risk.

## Repeat a request

Each scan has a request ID, which the CLI prints before it sends anything. The CLI never repeats a request on its own.

When the outcome is unknown because the connection failed, the server failed or its answer was unreadable, the command exits 4. Run it again with the same ref or commit, the same budget and the printed ID:

```sh
proofline scan --ref main --budget 200 --request-id 0199b000-0000-7000-8000-0000000000bb
```

Proofline returns the first resolution of that ID instead of starting and paying for a second scan. It does not resolve a moved ref again. Repeating the ID with a different repository, selection or budget is refused.

Repeating an ID that resolved to no scan still returns no scan: Proofline keeps that answer and does not ask GitHub again. The command exits 1, and with `--json` it prints the kept resolution with `"outcome": "EXISTING"` and `"review_id": null`. To try the ref again, for example after the branch has been pushed or the repository reconnected, run the command without `--request-id`, so it sends a new ID.

## Exit codes

Exits 0, 1 and 2 mean what they mean for `proofline review`:

| Exit | Meaning |
| --- | --- |
| 0 | The scan is complete; with `--no-wait` or a sign-in that cannot read reviews, the scan was accepted, not finished |
| 1 | The scan was refused, or the command failed |
| 2 | The scan is incomplete or has not finished |
| 4 | The outcome is unknown; repeat with `--request-id` |

## Request a scan over HTTP

The command sends `POST /repositories/{repo_id}/scans`. To send it yourself, use a token with `scans:request` and set `PROOFLINE_REPOSITORY_ID` to the repository's Proofline ID. Generate the request ID once and write it into the body file, so that a repeat sends the same ID:

```sh
REQUEST_ID="$(uuidgen)"
printf '{"request_id":"%s","ref":"main","budget_credits":200}\n' "$REQUEST_ID" > scan-request.json
SCANS="https://proofline.sh/api/v1/organizations/$PROOFLINE_ORGANIZATION_ID/repositories/$PROOFLINE_REPOSITORY_ID/scans"
curl -sS --fail-with-body -X POST "$SCANS" \
  -H "Authorization: Bearer $PROOFLINE_TOKEN" \
  -H "Content-Type: application/json" \
  --data @scan-request.json
```

Replace `ref` with `commit_sha` to name an exact commit. The [API reference](/docs/api/#request-scan) gives the request body and the response.

A successful response is a resolution receipt, not a result. Every receipt has a `resolution_id`, and it has a `review_id` only when a scan started, so read `outcome` and `review_id` before anything else:

| `outcome` | What happened |
| --- | --- |
| `CREATED` | GitHub resolved the selection and the scan was accepted; `review_id` names its review |
| `REPOSITORY_UNAVAILABLE` | GitHub could not resolve the selection; no scan started, nothing was spent and `review_id` is null |
| `EXISTING` | This request ID already has a receipt for the same body; Proofline returns it with its `review_id`, which is null if no scan started |

A fresh request whose ref resolves answers `CREATED`:

```json
{
  "resolution_id": "0199b000-0000-7000-8000-0000000000c1",
  "review_id": "0199b000-0000-7000-8000-0000000000c2",
  "outcome": "CREATED"
}
```

`CREATED` means the scan has started. Read the review with `GET /api/v1/organizations/{org_id}/reviews/{review_id}` and a token with `reviews:read` to learn whether it has finished and what it found. Its `status` ends `FAILED` or `INCOMPLETE` today, as [What a scan analyzes today](#what-a-scan-analyzes-today) explains, and its `finding_count` of 0 is not a result.

A ref that GitHub cannot resolve answers `REPOSITORY_UNAVAILABLE`, still with HTTP success:

```json
{
  "resolution_id": "0199b000-0000-7000-8000-0000000000d1",
  "review_id": null,
  "outcome": "REPOSITORY_UNAVAILABLE"
}
```

### Repeat an HTTP request

When the connection fails, the server answers with a 5xx status or its answer cannot be read, send the same `scan-request.json` again. Do not run `uuidgen` again; a new ID could start and pay for a second scan. If Proofline recorded the first attempt, the repeat answers `EXISTING` with that receipt's `resolution_id` and `review_id`, even if the ref has moved since. If it recorded nothing, the repeat answers as the first attempt would have. A request ID repeated with a different repository, selection or budget is refused with 400.

Repeating the request that answered `REPOSITORY_UNAVAILABLE` returns that receipt again, with no review:

```json
{
  "resolution_id": "0199b000-0000-7000-8000-0000000000d1",
  "review_id": null,
  "outcome": "EXISTING"
}
```

`EXISTING` with a null `review_id` means that no scan started. Proofline keeps that answer, so repeating the same body never asks GitHub again. To try the ref again, write a body with a new request ID and send it with the same `curl` command:

```sh
REQUEST_ID="$(uuidgen)"
printf '{"request_id":"%s","ref":"main","budget_credits":200}\n' "$REQUEST_ID" > scan-request.json
```

The new ID gets its own receipt: `CREATED` with a review if the ref now resolves, or `REPOSITORY_UNAVAILABLE` again if it does not.
