Skip to main content

Verifying CLI Releases

Every GitHub Release of overmindtech/cli is built by a public GitHub Actions workflow that produces SLSA Level 3 build provenance attestations via GitHub Artifact Attestations, signed by Sigstore, and published to the public Rekor transparency log. Each release archive is also accompanied by an SPDX-format Software Bill of Materials (SBOM) so your security tooling can ingest the dependency graph.

The signing identity is the workflow itself -- not a long-lived key Overmind holds. Anyone can verify that a binary they downloaded was built by our public release workflow at a specific tag and commit, without trusting Overmind to keep a private key safe.

What we sign and where it comes from​

The release workflow lives at .github/workflows/release.yml on overmindtech/cli. On every v* tag push it:

  1. Builds the binaries for Linux, macOS, and Windows via GoReleaser.

  2. Generates an SPDX SBOM for each release archive using Syft.

  3. Computes SHA256 checksums for every archive, package, and SBOM and writes them to checksums.txt.

  4. Calls actions/attest-build-provenance@v3 with subject-checksums: ./dist/checksums.txt. This produces one Sigstore-signed attestation per file listed in checksums.txt, all tied to the workflow identity:

    https://github.com/overmindtech/cli/.github/workflows/release.yml@refs/tags/v<version>

  5. Uploads the archives, the SBOM .spdx.json files, the Linux packages, and checksums.txt to the GitHub Release.

Every attested file is also visible on the Attestations tab of the public repo.

The GitHub CLI (v2.49+) ships with gh attestation verify, and is preinstalled on every GitHub-hosted runner. This is the lowest-friction option for CI use and the option we recommend.

# Pick a release tag (use `latest` to get the newest)
TAG=v1.2.3

# Download the archive for your OS/arch
gh release download "$TAG" \
  --repo overmindtech/cli \
  --pattern 'overmind_cli_*Linux_x86_64.tar.gz'

# Verify the build provenance attestation
gh attestation verify overmind_cli_*Linux_x86_64.tar.gz \
  --repo overmindtech/cli

gh attestation verify exits non-zero if the attestation is missing, signed by the wrong workflow, or no longer matches the file's SHA256. Wire it into a pipeline by checking the exit code or by passing --format json and asserting on cert-identity.

Verifying with cosign (no GitHub dependency)​

cosign verifies Sigstore bundles directly and does not require the gh CLI or a GitHub token. Use this if you don't want to depend on gh, or if your runners can't reach the GitHub API but can reach rekor.sigstore.dev.

TAG=v1.2.3
PATTERN='overmind_cli_*Linux_x86_64.tar.gz'

# Download the archive
gh release download "$TAG" --repo overmindtech/cli --pattern "$PATTERN"

# Resolve the glob to a concrete filename and download the matching bundle
ARCHIVE=$(ls $PATTERN)
gh attestation download "$ARCHIVE" --repo overmindtech/cli

# Verify with cosign, pinning the expected workflow identity
cosign verify-blob-attestation \
  --bundle "$ARCHIVE.sigstore.json" \
  --new-bundle-format \
  --certificate-identity-regexp '^https://github\.com/overmindtech/cli/\.github/workflows/release\.yml@refs/tags/v.+$' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  "$ARCHIVE"

The --certificate-identity-regexp and --certificate-oidc-issuer flags are what bind the verification to our release workflow specifically -- without them, cosign would accept an attestation signed by any GitHub Actions workflow.

If your environment can't reach github.com but can reach a GitHub Enterprise Server instance with the bundle mirrored, point gh attestation download at that instance instead (GH_HOST=ghe.example.com).

Verifying the SBOM​

Every release archive ships with a sibling *.spdx.json SBOM file as a release asset, suitable for ingestion by Snyk, Grype, Trivy, Dependency-Track, or any other SCA tool that consumes SPDX 2.3.

The SBOM files are not themselves Sigstore-attested in the current release, but they are included in checksums.txt and their SHA256 hashes are published alongside every release. You can verify the SBOM's integrity by checking it against checksums.txt, and then verify checksums.txt itself via its build-provenance attestation.

TAG=v1.2.3
SBOM_PATTERN='overmind_cli_*Linux_x86_64.tar.gz.spdx.json'

gh release download "$TAG" --repo overmindtech/cli \
  --pattern "$SBOM_PATTERN" \
  --pattern 'checksums.txt'

# Verify checksums.txt came from our workflow
gh attestation verify checksums.txt --repo overmindtech/cli

# Verify the SBOM matches the published hash
sha256sum -c checksums.txt --ignore-missing

# Resolve the SBOM glob to a concrete filename
SBOM=$(ls $SBOM_PATTERN)

# Inspect the dependency list (or hand off to your SCA tool)
jq '.packages[] | {name, versionInfo, downloadLocation}' "$SBOM"

If your SCA tooling or compliance framework requires a typed SBOM attestation (predicate-type https://spdx.dev/Document), contact us at engineering@overmind.tech and we can enable it.

Verifying via checksums.txt​

If you cannot install gh or cosign, you can still get a base level of integrity by checking the published SHA256 sums. checksums.txt is itself attested, so the moment you successfully verify it once with gh attestation verify (on any machine that can run it) you inherit the same provenance guarantee for every file that hashes correctly against it.

TAG=v1.2.3
gh release download "$TAG" \
  --repo overmindtech/cli \
  --pattern 'overmind_cli_*' \
  --pattern 'checksums.txt'

sha256sum -c checksums.txt --ignore-missing

This is the lowest bar -- it proves the file matches the digest we published, but on its own it does not prove the digest was produced by our release workflow. Pair it with one gh attestation verify checksums.txt --repo overmindtech/cli to close that gap.

Linux package signatures (Cloudsmith)​

The apt, yum, and apk install paths use Cloudsmith and are signed with Cloudsmith's GPG (deb/rpm) and RSA (apk) keys. The signature is verified automatically by your package manager during apt-get install / yum install / apk add, provided you set up the repository as described on the CLI Installation page (which imports the public key as part of the setup).

The Cloudsmith public keys can be downloaded from:

The build-provenance attestations described on the rest of this page do not currently extend to the .deb/.rpm/.apk packages -- those rely on Cloudsmith's signing infrastructure. If you need Sigstore attestations for the Linux packages, please contact us.

Container image (ghcr.io/overmindtech/cli)​

The container image is built by Depot and ships with an OCI SBOM attached to the image manifest. There is no Sigstore build-provenance attestation on the image today.

Inspect the SBOM with docker buildx imagetools inspect:

docker buildx imagetools inspect ghcr.io/overmindtech/cli:latest \
  --format '{{ json .SBOM }}' | jq

If you need Sigstore attestations for the container image, please contact us.

What verification proves -- and what it doesn't​

Verification confirms three things:

  • The binary you downloaded is byte-for-byte identical to the one our release workflow produced.
  • It was built by our public, auditable release workflow at a specific tag and commit -- not by an attacker who compromised an Overmind employee's laptop or a long-lived signing key.
  • The signing identity is recorded in the public Rekor transparency log, so any future attempt to repudiate or backdate the signature is detectable.

Verification does not prove:

  • That the source code is free of bugs or backdoors -- that is what code review and our SDLC are for.
  • That the dependency graph is free of vulnerabilities -- that is what the SBOM and your SCA tooling are for.
  • That a future release will not introduce a regression -- pin to specific tags rather than latest if your security policy requires version pinning.

If your security team has further questions, reach out at engineering@overmind.tech or open an issue on overmindtech/cli.