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_idis 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 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:
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:
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:
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:
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:
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:
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:
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:
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 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:
{
"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 explains, and its finding_count of 0 is not a result.
A ref that GitHub cannot resolve answers REPOSITORY_UNAVAILABLE, still with HTTP success:
{
"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:
{
"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:
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.