What a green check proves

A green shipcheck/<job> check on a PR means shipcheck ran that job on the PR's tree, with the config from main, and the job passed. The rules below hold for every check.

What it guarantees

How it knows it tested the right code

A check names the code it tested by hashes, and shipcheck checks each hash itself instead of trusting a file or a caller.

  1. The commit names its code. Git names every commit and tree by a hash of its content, so a tree id is a hash of every file in the commit. A result belongs to a tree. After a rebase or a push the PR has a new head commit. The daemon takes that commit's SHA from GitHub, fetches it and reads its tree. A new tree runs again. A tree that was already tested, such as a rebase that changed nothing, reuses its result.
  2. Each job's files are that tree. After the clone and before the job starts, shipcheck hashes every tracked file on disk again, into an index with no cached file times. The tree written from that index must be the tested tree. An edited, deleted or relinked file, or a changed mode, fails the job. Build output and untracked files are not part of a tree.
  3. The build starts from those files. Every tracked file gets the run's start time, so cargo, make and other tools that compare file times rebuild the code from this tree. They never trust output another tree left.
  4. What the check shows is true before it is posted. Before any pass is posted, stored or fresh, shipcheck checks it again. Its tree must be the commit's tree, its base must be on the current main, and each log must hash to the digest in the result. A stored result that fails this does not count, and the commit runs again. A fresh one is posted as a failure.

Check it yourself

The shipcheck check on a PR lists the Tree, the Base, the Key and a Log SHA-256 per workflow. From a clone of the repository:

FieldCommandHolds when
Treegit rev-parse <sha>^{tree}, with <sha> the PR's headit prints the Tree
Basegit merge-base --is-ancestor <base> origin/<branch>, with <branch> the default branch git ls-remote --symref origin HEAD reportsit exits 0
Log SHA-256shasum -a 256 ~/.local/state/shipcheck/logs/<key>/<workflow>.log on the machine that ran it, where <workflow> is the workflow file or host for host checksthe first 12 hex digits are the Log SHA-256

shipcheck logs <sha> prints the same logs. The Key is a hash of the tree, the config on main, the workflows as they ran, the tool versions, the shipcheck version and the images. Only a machine with the same tools gets the same Key, so it shows when two results came from the same inputs.

What it does not prove

Limits has the full list.

Previous: How it works Next: Security