Skip to content

Diff scans

View .md

A diff scan audits one change instead of the whole repository. It reads the code that changed between a base and a head commit. The rest of the repository is context, not a target. That makes it cheap and fast.

  • The head is the commit you scan. Set it with commitHash or branch, as for any scan.
  • The base is what the change is measured from. It can be a commit SHA, a branch, or a tag.

zkao compares the two on GitHub and audits the change from their merge base to the head. The scan records that merge base SHA as its baseCommit. So a base branch that moved on since you branched off does not pull its new commits into the diff.

  1. Push the head commit to GitHub. zkao reads both commits from there.
  2. Launch with a diff preset and a base. builtin:Flash Diff is the cheap one. builtin:Max Diff runs every technique on flagship models.
  3. Wait for it, as for any scan. See Run scans.
Terminal window
zkao scans launch --repo <repoId> --preset "builtin:Flash Diff" \
--base main --commit <headSha>
zkao scans wait <scanId>

Confirm the preset ref with zkao presets. The budget works as for any scan. Leave it out to use the recommended budget. It is sized from the change, up to three times the preset’s minimum. When no earlier scan of the repository built its overview, the diff scan builds one first. That scan takes longer, and its minimum and recommended budgets are higher. The launch response then sets buildsOverview to true. You can also give a diff scan per-scan guidance.

Only a diff scan preset takes a base, and it always needs one.

Status Code Cause
400 diff_base_required A diff scan was launched without a base.
400 diff_base_not_allowed A base was sent with a preset that is not a diff scan.
400 diff_base_invalid The base is not a valid name, does not exist, or shares no history with the head.
422 diff_empty The head changes nothing since the base. There is nothing to audit.

The message says which case applies. A failed comparison on GitHub’s side returns 400 bad_request. That one is transient, so retry it later.

Diff scans fit pull requests. Use the pull request’s base branch as the base and its head commit as the head.

The zkao GitHub Action does this for you with scan: flash or scan: max. It picks the pull request’s base, or the commit before a push. It can also fail the job when the scan finds issues above a severity.