HealkiteDocs

Verified builds

For banks, health and enterprise apps: prove where every update came from, and refuse anything else.

Each release built in GitHub Actions carries a token signed by GitHub that names the repository, workflow, branch, commit and run. Healkite checks it, can check the pull request's approvals, and keeps a record of it signed with the server's key, which anyone can verify.

With a policy turned on, Healkite rejects releases that don't meet it, even releases signed with your code-signing key. A stolen signing key or a developer's laptop can't publish.

1. Send provenance from CI

Add id-token: write to your release workflow. The Healkite CLI and GitHub Action pick the token up automatically:

yaml
permissions:
  contents: read
  id-token: write

Every release built that way gets a Build provenance card in the dashboard:

✔ Verified · Built by acme/shop · 4f2c91ab · release.yml · run #812 · PR #381, approved by alice

2. Require it (optional)

Dashboard → your app → Settings → Build provenance → Require:

  • Repository: only builds from this repository (forks don't count).
  • Workflows (optional): only these workflow files, e.g. .github/workflows/release.yml.
  • Branches (optional): only builds of these branches, e.g. main.
  • Pull request approvals (optional): the commit must come from a merged pull request approved by at least N people besides its author. This reads reviews through the token you gave under Settings → CI; give it Pull requests: read as well.

When a release doesn't meet the policy, publishing fails with the reason, for example:

this app only accepts releases built by acme/shop's CI: PR #381 has 0 approval(s); 1 needed

Promoting a release to another channel, or sending it to specific devices, keeps its provenance. A release without matching provenance can't be promoted into an app that requires it.

3. Verify a record

sh
npx healkite provenance rel_01j…
✔ Signature valid (server key …Q8xA2w==)
v42 · bundle 3fd9c2a1b7e0…
Built from acme/shop@4f2c91ab (refs/heads/main) by .github/workflows/release.yml, run https://github.com/acme/shop/actions/runs/812/attempts/1
PR #381, approved by alice, merged by lead

--json prints the signed statement, the signature and the server's public key. The statement is signed with ECDSA P-256 (SHA-256) over its exact bytes. The public key is the one at /v1/config (manifestPublicKey), the same key your app uses to check update lists. You can keep the records (also downloadable from the dashboard) as audit evidence.

What it guarantees

  • Releases on an app with a policy were built by the named repository's GitHub Actions, from the recorded commit and branch, and (if set) from an approved pull request. GitHub signs that identity; Healkite checks it before accepting the release.
  • Your app still checks your code signature and Healkite's manifest signature on the device, as before. It doesn't check provenance itself: devices can only receive releases the server accepted.
  • Provenance proves where a build came from, not that the code is safe. Pair it with code review.