Skip to main content

atmos artifacts sign

Sign the immutable subject of a digest reference and store the signature evidence beside the artifact. Signing adds evidence without changing the artifact or its digests.

Experimental
atmos artifacts sign --help

Usage​

atmos artifacts sign <name>@sha256:<digest> --repository=<alias> [flags]

Examples​

# Sign an immutable digest reference
atmos artifacts sign 'components/terraform/vpc@sha256:<digest>' --repository=shared

# Accept Sigstore transparency log publication in CI
atmos artifacts sign 'components/terraform/vpc@sha256:<digest>' --repository=shared --yes

Behavior​

Sign accepts digest references only, because evidence must bind to an immutable subject. The digest can be the one the repository resolved (the OCI manifest digest on OCI repositories, the Record digest on local and S3) or the Record digest. Either one selects the same artifact and the same signed subject.

The signed subject is the portable Record for an Atmos package, so evidence survives changes of physical representation. For a foreign OCI image or an existing plugin release, the subject is the original manifest or index digest, which Atmos never rewrites. The result lists the subject and the stored evidence descriptors; when the digest you named differs from the subject, a message explains which subject was signed.

Signing uses the managed Cosign executable and public Sigstore keyless authentication. Locally, Cosign opens its identity-provider login flow. In supported CI environments Cosign can use the workload identity; for GitHub Actions, grant the job id-token: write. The signer identity and the signing event are recorded in the public transparency log. Registry authentication is separate from the signing identity.

Signing does not verify the artifact against your trust policy. Run atmos artifacts verify for that.

Sign takes the repository's write lock. The result reports the actual lock_scope.

Arguments​

digest-ref (required)

name@sha256:<digest>.

Flags​

--repository, -r (required)

Configured repository alias. Environment variable: ATMOS_ARTIFACTS_REPOSITORY

--yes, -y (optional)

Accept Sigstore transparency log publication without prompting. Environment variable: ATMOS_ARTIFACTS_YES

--format (optional)

Output format: text (default), json, or yaml. Environment variable: ATMOS_ARTIFACTS_FORMAT

Output​

Stdout carries outcome (created), ref, location, the digests, lock_scope, the subject (kind and digest), and one evidence entry per stored evidence blob. Stderr carries the status line, which reminds you that signing is not verification.

Errors​

Missing repository
Exit code 2. The hint lists the configured aliases.
Version reference
A name:version reference fails: sign accepts digest references only.
Digest names another artifact
A digest that is none of the subject, resolved, or Record digests of the resolved artifact is rejected, and no evidence is written.
Unsupported capability
No signer is available, the repository cannot store evidence for this subject kind or format, or it cannot provide the required lock scope. Nothing is written.

Every failure exits with a nonzero status. For failures reached while the command runs, --format=json or --format=yaml still writes the result to stdout with outcome: failed and an error field. Argument and flag parsing failures, such as a missing reference or an unknown flag, are rejected before the command runs and do not produce a structured result.

Related​