Docs menu

Operate

Signed build provenance

Every image CLI builds comes with a signed record of which repository, commit and builder made it, in the in-toto and SLSA formats, that anyone can check with CLI's public key.

Explain it

Every time CLI builds your app, it signs a record saying exactly which code it came from, which builder made it and when. Anyone can check that record with CLI's public key, so you can prove what's running in production.

How to use it: open any deploy in the dashboard to see its signed record. You rarely need to do anything else; it's there for security reviews, customer questionnaires and audits.

Because it's signed, nobody (CLI included) can quietly swap what's running or rewrite the history afterwards.

Every time CLI builds an image it signs a statement saying which repository and commit it came from, which builder made it and when. You (or your customers, or an auditor) can check that statement with CLI's public key alone, without trusting CLI's database or dashboard.

Why it matters

When something is running in production, you should be able to prove exactly what it is. Provenance answers "is this image really built from that commit?" for supply-chain reviews, SOC 2 evidence, customers' security questionnaires, and for your own peace of mind after an incident. Because the record is signed, nobody can quietly swap an image or rewrite history afterwards, CLI included.

What's signed

The record is an in-toto statement with a SLSA provenance v1 predicate, in a DSSE envelope signed with Ed25519. It names:

  • the image and its sha256 digest
  • the source: repository, commit, root directory
  • the builder and the deploy that ran it, with start and finish times

Prebuilt images (deployed from a registry) aren't signed: CLI didn't build them.

See it

On a deploy's page, Signed build shows the commit and digest. From the API or terminal:

GET /v1/deploys/:id/provenance
cli provenance dep_123

Check it yourself

Save the response, then:

npx tsx scripts/verify-provenance.ts provenance.json --keys https://<your CLI>/.well-known/cli-provenance-keys --commit 4f2c9e1

It prints what the record says and exits non-zero if the signature doesn't hold, or if --digest or --commit don't match. Changing anything in the record, even one character of the commit, breaks the signature.

The key

CLI signs with one Ed25519 key, published at /.well-known/cli-provenance-keys. Operators can set it with CLI_PROVENANCE_KEY (a 32-byte seed); otherwise it's derived from CLI_SECRET_KEY, so it stays the same across restarts and servers.