# 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.
