Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 16 additions & 1 deletion docs/custody-upgrade-runbook.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,28 @@ Use this to upgrade a `facet` binary installed under a root-owned prefix (`<pref

## Run order

1. **Verify the release.** `gh attestation verify <archive> --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/<version>/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 `<version>` is live.

## Verify the release

```bash
V=<version> # 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<version>` tag and that tag's commit, so an archive built from a branch or another workflow fails here.

## Lock and switch

```bash
Expand Down
13 changes: 9 additions & 4 deletions docs/install.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Loading