Imported from zircote/rust-template (.claude/skills/release/SKILL.md). Install upstream with npx skills add zircote/rust-template --skill release. Copyright stays with the author.

Release Orchestration

Run a complete attested release for this repository. The argument is either an explicit version (/release v1.4.0) or a bump type (/release patch|minor|major), which computes the target from the current Cargo.toml version. Every phase below ends with a verification; do not proceed past a failure — fix it or stop and report.

Project names are never hardcoded: resolve the crate/binary name from cargo metadata --no-deps and the owner/repo from gh repo view --json nameWithOwner at the start, and use those values everywhere <bin> and <owner>/<repo> appear below.

The pipeline this skill drives (all already wired in .github/workflows/):

prep PR ──merge──> tag push ──┬─> release.yml  (test + audit gates → 5 platform
                              │    binaries → provenance + SBOM attestations →
                              │    source snapshot + SCA/IaC-license gate
                              │    attestations → fail-closed verify →
                              │    GitHub Release)
                              ├─> publish.yml  (publish gate → pre-publish checks
                              │    → crates.io Trusted Publishing → download
                              │    registry .crate → sha256 match → attest)
                              └─> pipeline.yml (container: build → central
                                   sign-and-attest → fail-closed verify →
                                   Trivy image gate attestation)
release.yml completion ─workflow_run─> package-homebrew.yml (formula update)

The release.yml run is not just binaries: it also packs a published source snapshot tarball and attests two quality-gate verdicts (SCA via OSV-Scanner, IaC/license via Trivy) over it through the central reusable-attest-scan.yml seam, then fail-closed verifies every attestation — binaries (provenance + SBOM) and source (provenance + both gate verdicts) — before the GitHub Release is created. SAST (CodeQL) and posture (Scorecard) are enforced at merge time, not re-run here.

Help / no argument

If invoked with no argument, --help, or help, print this and stop — do not start a release:

/release — attested release orchestration

USAGE
    /release v<X.Y.Z>     release an explicit version (e.g. /release v1.4.0)
    /release patch        bump X.Y.Z -> X.Y.(Z+1) and release
    /release minor        bump X.Y.Z -> X.(Y+1).0 and release
    /release major        bump X.Y.Z -> (X+1).0.0 and release

WHAT IT DOES
    prep PR (version locations) -> required-checks green -> squash merge
    -> annotated tag -> monitors: attested binaries + SBOM + source
    snapshot + SCA/IaC-license gate attestations + fail-closed verify ->
    GitHub Release; crates.io Trusted Publishing + .crate attestation;
    attested container image; Homebrew auto-update -> independent
    workstation verification of every artifact.

NOTES
    - Publishing to crates.io is irreversible; versions are immutable.
    - CHANGELOG [Unreleased] must have content; empty means stop and ask.
    - Never re-runs release.yml against an existing tag (asset immutability).

Phase 0 — Preflight

0. External-publication gate — publish = false in Cargo.toml gates the EXTERNAL channels only: crates.io, the container image, and Homebrew. It does not gate the GitHub Release — a pushed tag always produces an attested GitHub Release (binaries + SBOM + source snapshot). Resolve which channels are armed and report it; do not stop:

   cargo metadata --no-deps --format-version 1 \
     | jq -r 'if .packages[0].publish == [] then "EXTERNAL PUBLISH DISABLED (GitHub Release only)" else "ALL CHANNELS ARMED" end'

   • If DISABLED: proceed — this release will create the attested GitHub Release and skip crates.io / container / Homebrew. State this plainly in the first progress message so the operator knows what will ship.
   • If ARMED: the full chain runs, including the irreversible crates.io publish — confirm that is intended before tagging (see Phase 4 caveats).
1. git checkout main && git pull; working tree must be clean of tracked changes (untracked noise is fine).
2. Resolve the target version from the argument:
   • v<major>.<minor>.<patch> → use as given.
   • patch | minor | major → read version from Cargo.toml on freshly-pulled main and bump that component, zeroing the lower ones (1.3.1 + minor → 1.4.0; 1.3.1 + major → 2.0.0).
   • Anything else → stop and ask. Strip the v for file edits; keep it for the tag. State the resolved version in the first progress message so a wrong bump is caught early.
3. Sanity checks, all hard stops:
   • New version is greater than version in Cargo.toml.
   • Tag does not already exist (git tag -l v<X.Y.Z>, and check remote).
   • CHANGELOG.md has content under ## [Unreleased] — a release with an empty changelog means something is off; ask the user what this release contains.
   • Latest pipeline run on main is green (gh run list --workflow=pipeline.yml --branch main --limit 1).
4. Semver gut-check: if Unreleased contains breaking changes or an MSRV bump and the user asked for a patch, raise it before proceeding.

Phase 1 — Release prep

Branch release/v<X.Y.Z> off main, then update all version locations (missing one ships inconsistent metadata):

Validate locally before the PR: cargo fmt -- --check and cargo check minimum. The PR's CI and the release workflow's own gates run the full suite, so don't duplicate the entire gauntlet here — but a broken lockfile or fmt failure should never reach the PR.

Commit as chore(release): v<X.Y.Z>, push, open the PR. The body should list what the release contains and note anything operator-relevant.

Phase 2 — PR through merge

Required status checks on main are CI Checks / All Checks Pass and pin-check / pin-check. Monitor the PR with the Monitor tool — and use the aggregate-gate guard, not a naive all-non-pending check:

# Terminal only when the aggregate gate check itself has reported and
# nothing is pending. Right after a push there is a window where only 1-2
# checks are registered; "zero pending" alone declares victory in that
# window (this produced a false ALL GREEN once).
gate=$(jq -r '[.[] | select(.name=="CI Checks / All Checks Pass")][0].bucket // "absent"' <<<"$checks")

When green, merge with gh pr merge --squash --delete-branch, then git checkout main && git pull and confirm HEAD is the release commit.

Phase 3 — Tag

Annotated tag on the merge commit, then push:

git tag -a v<X.Y.Z> -m "Release v<X.Y.Z>

<one-paragraph summary from the changelog>" <merge-sha>
git push origin v<X.Y.Z>

The tag push is the release trigger. Facts that matter here:

• Tag pushes bypass branch protection — release.yml carries its own test and audit gates precisely because the tag is untrusted input.
• Never re-dispatch release.yml against an existing tag. Builds are not reproducible; it would overwrite published release assets with different bytes, violating the immutability the attestations exist to protect.

Phase 4 — Monitor the chains

Four things run; watch all of them with the Monitor tool (one monitor, multiple conditions — report each as it lands):

1. Release run (release.yml). Expect all of these jobs to succeed:
   • Resolve Project Metadata (meta)
   • Test, Cargo Audit (untrusted-tag gates)
   • Build (<platform>) × 5
   • Source Snapshot (source) — packs and attests the published <bin>-<X.Y.Z>-source.tar.gz, the verifiable subject for the gates
   • Gate — SCA (OSV), Gate — Trivy (IaC/license) — the two quality-gate scans
   • Attest — SCA, Attest — IaC/license — gate verdicts signed over the source snapshot via the central reusable-attest-scan.yml seam
   • SBOM (generate + attest) (sbom)
   • Verify Attestations (verify) — fail-closed: binaries (provenance + SBOM) and source (provenance + both gate verdicts)
   • Create Release (release)
2. Publish run (publish.yml). Expect: Publish Gate (guard) resolves publishable, then in the Publish to crates.io job — "Run pre-publish checks", "Authenticate with crates.io" (Trusted Publishing), "Publish to crates.io" (cargo publish), then the crate-attestation steps "Download published crate from registry" (sha256 match against the local package) and "Attest crate provenance". Report these step conclusions explicitly.
3. Pipeline run (pipeline.yml, container chain on the tag). Expect: Docker build/push, Sign and Attest Image (central signer), Verify Image Attestations — and the container gate attestation pair Gate — Trivy (image) + Attest — Container scan. All success.
4. Homebrew run (package-homebrew.yml) must appear on its own after the Release run completes, via workflow_run. If no run appears within a few minutes of Release success, the trigger regressed — fall back to manual dispatch (gh workflow run package-homebrew.yml -f version=<X.Y.Z> -f dry_run=false) and investigate.

Failure playbook

Phase 5 — Independent workstation verification

In-pipeline success is necessary; this is the acceptance test. Run from the local machine, in a scratch dir:

gh release download v<X.Y.Z> --repo <owner>/<repo>
# Expect 8 assets: 5 binaries, <bin>-<X.Y.Z>-sbom.cdx.json,
# <bin>-<X.Y.Z>-source.tar.gz, and <bin>-<X.Y.Z>-checksums.txt

# Binaries: provenance + SBOM binding.
for f in <bin>-<X.Y.Z>-{linux-amd64,linux-arm64,macos-arm64,macos-amd64,windows-amd64.exe}; do
  gh attestation verify "$f" --repo <owner>/<repo>                  # provenance
  gh attestation verify "$f" --repo <owner>/<repo> \
    --predicate-type https://cyclonedx.org/bom                      # SBOM binding
done

# Source snapshot: provenance (this repo) + the two seam-signed gate verdicts.
gh attestation verify <bin>-<X.Y.Z>-source.tar.gz --repo <owner>/<repo>
for pt in sca iac-license; do
  gh attestation verify <bin>-<X.Y.Z>-source.tar.gz --owner <owner> \
    --signer-workflow zircote/.github/.github/workflows/reusable-attest-scan.yml \
    --predicate-type "https://zircote.github.io/attestations/${pt}/v1"
done

shasum -a 256 -c <bin>-<X.Y.Z>-checksums.txt

# crates.io: needs a User-Agent or the API/CDN rejects silently
curl -fsSL -A 'release-check' \
  -O https://static.crates.io/crates/<name>/<name>-<X.Y.Z>.crate
gh attestation verify <name>-<X.Y.Z>.crate --repo <owner>/<repo>

# Container image (digest from the pipeline run's docker job output):
gh attestation verify "oci://ghcr.io/<owner>/<repo>@<digest>" \
  --repo <owner>/<repo> \
  --signer-workflow <owner>/.github/.github/workflows/sign-and-attest.yml \
  --predicate-type https://slsa.dev/provenance/v1

Check exit codes, not grepped output — a filtered pipe that matches nothing looks identical to success (this mistake was made once; silence is not success). No --signer-workflow flag for binary provenance/SBOM or the crate: those are attested by this repo's own workflows. Two things DO need --signer-workflow: the source-snapshot gate verdicts (signed by the central reusable-attest-scan.yml seam) and the container image (signed by the central sign-and-attest.yml).

Confirm crates.io shows the version: curl -s -A 'release-check' https://crates.io/api/v1/crates/<name> | jq .crate.max_version

Final report

Summarize for the user: version, merge commit, tag; per-channel status (GitHub Release / crates.io / container image / Homebrew); workstation verification results (binaries, source snapshot + gate verdicts, crate, image); and anything from the failure playbook that fired. If any channel is incomplete, say exactly what is pending and what unblocks it.