Skip to main content

Scan a repository

A scan checks supported workspace practices against files on a monitored repository's default branch. GitHub and GitLab support scans. Slack and Outline do not. Scans produce admin reports, not developer feedback or personal standing.

Start a scan​

A workspace admin or owner can start a scan through a repository schedule or the API. The Scans page lists scans and their reports.

  1. Open Review settings in workspace administration.
  2. Under Add a recurring check, select Repositories in Kind of work.
  3. Select How often.
  4. Enter Budget per run (USD).
  5. Select Start checking repositories.

The schedule scans repositories in the workspace review scope. For an immediate scan, send a POST /workspaces/{slug}/practices/scans request. The request requires the workspace Admin role or Owner role.

curl --request POST "$HEPHAESTUS_API_URL/workspaces/acme/practices/scans" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 89c54bc9-3148-42d0-9354-d0d8bd571f3a' \
  --data '{"repositoryItemId":"123","ref":null,"expectedVersion":null,"practiceSlugs":null,"budgetUsd":"5.00","reuse":true}'

Set HEPHAESTUS_API_URL to the server API base URL. Use an access token for a workspace admin or owner. Replace acme with the workspace slug and 123 with the monitored repository item ID. A null practiceSlugs value selects all eligible practices with scan support. Use a new UUID for each new request. Keep its Idempotency-Key and body unchanged when you retry after an uncertain response.

The scan pins the default-branch commit before execution. A different branch is refused. The branch cannot move within this scan. Only one scan per workspace can be active. A repeated request with the same identity and body returns the same scan. A changed body with that identity is a conflict, not a second scan.

Read the report​

Files counts distinct eligible file items. Outcome counts describe practice/file pairs, so a file can contribute to several practices. Reviewed counts new observations from this scan. Reused counts earlier observations used again. The tables show their combined total as Reviewed or reused. The report separates these facts:

  • Observations judged in this scan.
  • Observations reused from earlier reviews with equal proof identity and method.
  • Withheld pairs with recorded refusal reasons.
  • Not reviewed pairs left untouched when the scan closed.
  • Listing completeness and execution completion.

The report API lists binary files and files above 2 MiB as exclusions, with their paths, sizes and reasons. These files remain in the repository inventory. They do not count as eligible files or produce outcomes. Exclusions do not prevent completion of the eligible work. Null means that the scan did not record exclusions or that the raw inventory expired.

Complete requires a complete listing and every selected pair judged or reused. Withheld or unreached work produces Partial. Failed and Cancelled retain the work already reached. A valid empty selection has zero pairs, not a fabricated Met observation. Incomplete listing has no invented total file count.

Recorded counts preserve the totals at closure. Current open-problem counts exclude accepted, incorrect or inaccessible proof. Accepting an observation changes open counts without changing its recorded outcome. A hidden quotation does not imply that no problem exists.

Compare scans​

Comparison uses the previous terminal scan of the same repository and default branch. Each practice needs equal selectors, review digest and frozen model method. A changed standard or method starts a comparison break.

A reused observation keeps its original producer review. The report links through the scan's durable membership. A model change or changed context requires a new judgment. Reuse currently requires the same assigned file blob and declared context inventory. A change to any file in that context prevents reuse, even if the earlier execution did not read it. With repository-wide context, an unrelated file change can therefore prevent reuse for every selected file.

New, Unchanged and Updated describe comparable problem identities. Absent requires complete new proof at a changed file version. A complete Not met observation can prove one earlier problem absent while recording another problem.

Met can also establish repair within its evidence boundary. Missed reads, withholding, marks, applicability exclusions and removed files do not prove absence. Completed files in a partial scan can establish their own comparison. The unreached remainder cannot.

Read listing warnings​

The removal guard uses the entire repository inventory before practice filters. An incomplete listing or a suspect listing removes no files or current observations. A changed selector cannot make a real repository file disappear. Renaming a file creates a new file item. It is not a claimed repair.

Cancel a scan​

  1. Open the active scan.
  2. Select Cancel scan.
  3. In the confirmation dialog, select Cancel scan.

Cancellation waits for the active execution job to settle. The report keeps admitted work and identifies the unreached remainder. Start a fresh scan to review again. A cancelled scan does not silently restart.

Schedules​

Repository schedules freeze target repositories and a budget in their batch. Targets execute serially through the same scan driver. Pause stops new targets and cancels active scan work through its normal cancellation boundary. Resume continues the uncreated targets in the frozen batch. A schedule with referenced batches cannot be deleted until those references are gone.

Export SARIF​

  1. Open the terminal scan report.
  2. Select Export SARIF.

An active scan cannot export its report. A partial terminal export states that execution did not complete. Each visible problem becomes one SARIF result. Coverage totals remain separate. Marks and erasure can exclude proof without rewriting close-time totals.

Raw scan proof expires after 400 days (Data retention). Expired proof pages and SARIF exports are unavailable, while aggregate reports remain readable. Data retention owns the retention periods.

Cost and limits​

A scan freezes its budget and complete model-slot method. Unknown priced cost remains unknown. It is never treated as free budget spend. A budget, deadline or required source refusal leaves explicit Withheld or Not reviewed work. The AI provider guide owns model limits and prices.