Signing a release gives users a way to check that an artifact came from your project and was not altered after publication. This guide presents a reusable Sigstore and Cosign workflow for container images, binaries, and provenance attestations, with practical CI/CD checks, verification commands, and a release checklist.
Overview
Software signing is most useful when it is part of the release process rather than an emergency task performed after an incident. A complete workflow answers four questions:
- What was signed? Identify the immutable artifact, such as a container image digest, binary checksum, or attestation.
- Who or what signed it? Use a key, a trusted CI identity, or another documented signing identity.
- Where is the verification information? Publish signatures and verification instructions alongside the release.
- What should happen if verification fails? Treat a missing, invalid, or unexpected signature as a release investigation, not as a warning to ignore.
Cosign is commonly used with Sigstore services and OCI registries to sign container images and related artifacts. Depending on the workflow, a project may use keyless signing through an identity-backed CI job or traditional key-based signing. Keyless signing can reduce long-lived private-key handling, while key-based signing may fit offline releases, established organizational controls, or environments that already manage signing keys. Confirm the behavior, flags, registry support, and trust model for the Cosign version and Sigstore components used by your project before standardizing commands.
| Artifact | Typical signing approach | Verification focus |
|---|---|---|
| Container image | Sign the image digest and store the signature with the registry artifact | Verify the digest, signer identity, and expected repository |
| Binary or archive | Sign the file or publish a signed checksum or attestation | Check the downloaded file against the signed release record |
| Build provenance | Attach an in-toto or compatible provenance attestation | Review builder, source revision, materials, and declared predicates |
| SBOM | Attach or sign the SBOM as a release artifact | Confirm it belongs to the exact build being evaluated |
Signing does not by itself prove that the source code is safe or that a build process was correctly configured. It establishes a verifiable relationship between an identity, a statement, and an artifact. Pair release signing with dependency review, SBOM generation, and license checks; the SBOM generation and review guide and license compliance workflow cover those adjacent controls.
Checklist by scenario
Scenario 1: Sign a container image in a registry
- Build the image and push it to the registry.
- Resolve and record the immutable digest. Prefer a digest over a mutable tag such as
latest. - Sign the digest with the project’s approved identity or key.
- Record the image reference, digest, release version, signer, and verification policy.
- Test verification from a clean environment before announcing the release.
A keyless flow may resemble the following, subject to the installed Cosign version and the registry’s support:
cosign sign registry.example.org/project/app@sha256:IMAGE_DIGEST
cosign verify \
--certificate-identity-regexp 'release-workflow-identity-pattern' \
--certificate-oidc-issuer 'expected-issuer' \
registry.example.org/project/app@sha256:IMAGE_DIGEST
Do not copy identity patterns without defining what they should match. A verification rule should be narrow enough to distinguish the project’s release workflow from unrelated identities. If your project uses a public key instead, keep the verification key in a documented, access-controlled location and use the key explicitly during verification.
Scenario 2: Sign binaries and archives
- Build the release in a clean, reproducible or well-documented environment.
- Generate checksums for each binary and archive.
- Sign the artifact or the release manifest containing its checksums.
- Publish the artifact, signature, checksum information, and verification instructions together.
- Verify a downloaded copy after transfer, ideally on a separate machine or in an isolated job.
The important detail is binding the signature to the exact bytes users download. A signature for a version label, branch name, or mutable URL is weaker operationally than a signature tied to a specific file digest or immutable release record.
Scenario 3: Publish provenance attestations
Provenance describes how an artifact was produced. It may include the source revision, builder, build invocation, dependencies or materials, and output digest. Treat it as a separate statement from the signature: the signature protects the statement’s integrity and origin, while the provenance fields provide the build context.
In CI, generate provenance after the artifact is built, attach it to the same immutable artifact reference, and verify that the attestation names the expected source revision. Keep the predicate type and required fields documented so consumers know what your project promises and what it does not.
Scenario 4: Add signing to CI/CD
A release job should sign only after tests, packaging, and release approval have passed. Restrict signing permissions to release workflows, avoid exposing signing credentials to ordinary pull-request jobs, and separate build permissions from publication permissions where practical.
steps:
- name: Build and push image
run: ./ci/build-and-push.sh
- name: Resolve immutable image reference
run: ./ci/write-image-digest.sh
- name: Sign release image
run: cosign sign "$IMAGE_DIGEST_REFERENCE"
- name: Verify release image
run: ./ci/verify-release-image.sh "$IMAGE_DIGEST_REFERENCE"
The example intentionally leaves identity, authentication, and registry details to the CI provider. Store no private key, token, or certificate material in repository files. For self-hosted runners, review isolation, network access, cleanup, and secret exposure using the self-hosted CI/CD runner guide.
What to double-check
- Digest versus tag: Verification should target the digest that was signed. A tag can move after signing.
- Identity constraints: Document the expected issuer, subject, repository, workflow, or key fingerprint. Avoid accepting any valid signature without checking who created it.
- Registry behavior: Confirm that signatures and attestations remain discoverable after image copying, mirroring, garbage collection, or retention policies.
- Attestation format: Record the predicate type and required fields. Consumers need to know how to interpret the statement.
- Release documentation: Add a short verification example to each release or to a stable security document. Include the exact artifact reference.
- Failure handling: Decide whether a missing or invalid signature blocks deployment, creates an alert, or requires manual approval. Express that decision in CI policy rather than tribal knowledge.
- Policy integration: If a cluster admission controller, registry policy, or deployment gate verifies signatures, test both accepted and rejected images. A policy that is never tested can fail open operationally or block legitimate releases unexpectedly.
A consumer verification template can be as simple as:
# 1. Copy the exact artifact reference from the project release notes.
ARTIFACT='registry.example.org/project/app@sha256:RELEASE_DIGEST'
# 2. Verify the signature using the project's documented identity or key.
cosign verify "$ARTIFACT"
# 3. Confirm the output matches the expected project, release workflow,
# source revision, and artifact digest.
# 4. Stop if verification fails or the identity is unexpected.
Consumers should not replace a failed verification with a download from an alternate mirror unless the project documents how that mirror is trusted and how the artifact digest is compared.
Common mistakes
- Signing mutable tags: A signature may be valid while the tag now points to different content. Sign and verify immutable references.
- Publishing a signature without instructions: Users need the expected identity, issuer or key, artifact reference, and a command they can run independently.
- Using broad verification rules: “Any valid signature” is rarely the intended trust policy. Match the project’s documented signer.
- Signing before the final build: Rebuilding, repackaging, or modifying an image after signing invalidates the relationship users are checking.
- Exposing signing authority to untrusted jobs: Pull-request code should not automatically receive the credentials or identity permissions used for public releases.
- Ignoring failed checks: A failed signature check can indicate a wrong digest, a registry issue, an expired or changed identity configuration, or tampering. Record the result and investigate.
- Assuming signing proves quality: A valid signature identifies an origin or authorized workflow; it does not replace tests, review, dependency controls, or incident response.
Keep rollback procedures aligned with release verification. If a signed image is withdrawn or replaced, document which digest is affected and how users should move to the approved replacement. The CI/CD rollback and incident response playbook can help turn that response into an operational procedure.
When to revisit
Review this workflow before a major release, CI migration, registry migration, signing-policy change, or verification audit. Also revisit it at least twice yearly, and sooner when the Cosign command behavior, Sigstore service, registry integration, attestation format, or deployment policy changes.
Use this short maintenance checklist:
- Run verification from a clean environment using the commands published for the current release.
- Confirm that a known-good artifact passes and a deliberately altered artifact fails.
- Check that the expected signer identity and issuer still match the release workflow.
- Verify that signatures and attestations survive the project’s registry retention, mirroring, and promotion process.
- Review CI permissions, runner isolation, secrets, and approval gates.
- Update release notes, policy examples, and consumer documentation when commands or trust assumptions change.
Start with one release path, document the exact artifact reference and trust rule, and make verification a required CI or deployment step where the project’s risk warrants it. Then extend the same pattern to binaries, SBOMs, and provenance attestations without changing the underlying principle: publish what was signed, identify who signed it, and define what happens when verification does not pass.