Sign Release Binaries
Unsigned releases are indistinguishable from a malicious mirror's copy. A signature with a published identity and a documented verification command turns trust into a check.
Procedure
- Decide the mode. Keyless (Sigstore/OIDC) ties the signature to a CI workflow identity and needs no stored secret; a managed key (KMS,
gpg) suits air-gapped or non-CI releases. - Keyless in GitHub Actions — give the job
id-token: writeand sign the built artifacts:cosign sign-blob --bundle dist/app.sigstore dist/app - Detached GPG for key-managed releases. Use a dedicated release key, not a personal one:
gpg --armor --detach-sign --local-user releases@example.org dist/appExport the public key once per major version:gpg --armor --export releases@example.org > release-key.asc. - Sign containers by digest, not tag:
cosign sign registry/app@sha256:<digest>. - Sign the checksum file too, so a user can verify many artifacts from one trusted root:
sha256sum dist/* > SHA256SUMS && cosign sign-blob --bundle SHA256SUMS.sigstore SHA256SUMS. - Publish signatures next to the artifacts, plus a short
VERIFY.mdwith the exact command and the expected certificate identity or key fingerprint. - Store any long-lived signing key encrypted (age/GPG) and available only to the release job; never commit it.
Pitfalls
- Signing before the artifact is final (still gets a timestamp or repack) invalidates the signature; sign the exact bytes you ship.
- Re-signing an artifact with a new key after a compromise does not un-publish the old signature — revoke the key and tell users.
- A signature proves integrity and identity, not safety; pair it with provenance and an SBOM.
- Keyless signatures embed a short certificate lifetime; verification depends on the Rekor transparency log, so do not delete the bundle.
- Committing a passphrase-free private key to CI secrets is a leak waiting to happen; scope the token to the release environment.
Verification
cosign verify-blob --bundle dist/app.sigstore \
--certificate-identity-regexp '^https://github.com/org/repo/' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com dist/app
For GPG: gpg --verify dist/app.asc dist/app prints Good signature from releases@example.org. Both must pass with the documented identity.
Report: "Signed keyless from ; verification command in VERIFY.md returns Verified OK for identity ."