diff --git a/docs/custody-upgrade-runbook.md b/docs/custody-upgrade-runbook.md index 3d4d5eaa..2e584ce8 100644 --- a/docs/custody-upgrade-runbook.md +++ b/docs/custody-upgrade-runbook.md @@ -4,13 +4,28 @@ Use this to upgrade a `facet` binary installed under a root-owned prefix (` --repo Hedronite/facet` must pass. After you extract the archive, record `shasum -a 256 facet` and check it against the attested release digest (`SHA256SUMS`, which is attested too). +1. **Verify the release.** Before you extract anything, check that the release workflow built the archive and `SHA256SUMS` from the tag you mean to install (block below). Both `gh attestation verify` runs must exit 0, and `shasum -c` must print `OK`. After you extract the archive, record `shasum -a 256 facet`: that is the sha the allowlist pins. 2. **Install under the root prefix.** Put the binary at `$D/facet//facet` (root-owned) and stage the allowlist that matches the version. 3. **Lock and switch** (block below). 4. **Post-checks** (below). Do not go on until every check passes. 5. **Smokes and QA.** Run `facet --version`, `facet doctor --json`, and your usual smoke runs against the live path. 6. **Announce downstream.** Tell dependent hosts or users that `` is live. +## Verify the release + +```bash +V= # e.g. 0.8.0 +T=$(gh api repos/Hedronite/facet/commits/v$V --jq .sha) # the commit the tag points at +for f in facet-cli-$V-macos-arm64.tar.gz SHA256SUMS; do + gh attestation verify $f --repo Hedronite/facet \ + --signer-workflow Hedronite/facet/.github/workflows/release.yml \ + --source-ref refs/tags/v$V --source-digest $T +done +shasum -a 256 -c SHA256SUMS --ignore-missing # the archive matches the attested digest list +``` + +`--repo` alone accepts an attestation from any workflow in the repo, built from any ref. The three pins tie it to `release.yml`, the `v` tag and that tag's commit, so an archive built from a branch or another workflow fails here. + ## Lock and switch ```bash diff --git a/docs/install.md b/docs/install.md index ba9f4212..319a0e9f 100644 --- a/docs/install.md +++ b/docs/install.md @@ -99,14 +99,19 @@ facet --version ### Release archive provenance -Release archives from 0.8.0 on carry a signed build provenance attestation (keyless, via GitHub and Sigstore), and so does `SHA256SUMS`. Before you extract an archive, check that the release workflow in `Hedronite/facet` built it: +Release archives from 0.8.0 on carry a signed build provenance attestation (keyless, via GitHub and Sigstore), and so does `SHA256SUMS`. Before you extract an archive, check that `release.yml` in `Hedronite/facet` built it from the `v0.8.0` tag: ```bash -gh attestation verify facet-cli-0.8.0-macos-arm64.tar.gz --repo Hedronite/facet -gh attestation verify facet-cli-0.8.0-linux-x64.tar.gz --repo Hedronite/facet +T=$(gh api repos/Hedronite/facet/commits/v0.8.0 --jq .sha) # the commit the tag points at +for f in facet-cli-0.8.0-macos-arm64.tar.gz SHA256SUMS; do # linux: facet-cli-0.8.0-linux-x64.tar.gz + gh attestation verify $f --repo Hedronite/facet \ + --signer-workflow Hedronite/facet/.github/workflows/release.yml \ + --source-ref refs/tags/v0.8.0 --source-digest $T +done +shasum -a 256 -c SHA256SUMS --ignore-missing # linux: sha256sum -c SHA256SUMS --ignore-missing ``` -It needs the [GitHub CLI](https://cli.github.com/), logged in. It exits non-zero when the file has no valid attestation from this repo, so do not run that binary. Releases before 0.8.0 have no attestation. +It needs the [GitHub CLI](https://cli.github.com/), logged in. `--repo` alone accepts an attestation from any workflow in the repo, built from any ref; the other three flags tie it to the release workflow and the tag. Each command exits non-zero when the file has no matching attestation, so do not run that binary. Releases before 0.8.0 have no attestation. ### Installed binary