Skip to main content

atmos artifacts

Publish files and directories as named, versioned artifacts, then pull, copy, inspect, list, search, sign, and verify them from one command space. Repositories live in local directories, local archives, S3 buckets, and OCI registries or layouts, and each one is addressed by an alias that you define in atmos.yaml.

Experimental
Configure Artifact Repositories

Define repositories, authentication identities, packaging, write coordination, and signature verification policy under the top-level artifacts section of atmos.yaml.

atmos artifacts --help
 

Usage​

atmos artifacts <subcommand> [flags]

Quick Start​

Define artifact-writer under auth.identities first, then define two repositories, publish a directory to one, and copy it to the other:

artifacts:
repositories:
backups:
kind: local/dir
options:
path: ./.artifacts/backups
shared:
kind: aws/s3
identity: artifact-writer
options:
bucket: acme-artifacts
prefix: shared
atmos artifacts publish ./dist --repository=backups --name=builds/app --version=build-123
atmos artifacts list --repository=backups
atmos artifacts copy builds/app:build-123 --from=backups --to=shared
atmos artifacts pull builds/app:build-123 --repository=shared --output=./restore

Repositories and References​

A repository is a collection root that holds many named artifacts. The keys under artifacts.repositories (backups, shared) are arbitrary aliases that you choose, and every command selects a repository by alias with --repository. A command that needs a repository fails when you omit it, even when only one is configured. Only list and search default to all configured repositories.

An artifact reference takes one of two forms:

name:version

A name and an explicit version label, for example components/terraform/vpc:1.2.0. Names are lowercase, slash-separated paths. Versions follow the OCI tag grammar and are opaque labels; they do not need to be SemVer. A reference without a version is rejected, because there is no implicit latest.

name@sha256:<digest>

An immutable digest reference. sign accepts only this form. Other commands accept it wherever they accept name:version.

Artifact Kinds​

The kind says what the content means: files for any tree, scaffold for a validated scaffold template, and component/terraform for a Terraform root module that leaves out working directories, state, and saved plans. atmos scaffold publish supplies the scaffold kind for you. See Artifact Kinds for what each kind validates, excludes, and records.

Digests​

Results label each digest by what it identifies:

resolved_digest

The digest the repository resolved the reference to. On OCI repositories it is the manifest or index digest. On local and S3 repositories it is the Record digest.

record_digest

The digest of the portable Record, which binds the name, version, metadata, inventory, content digest, and document digests. For Atmos packages, signatures cover the Record, so evidence survives changes of physical representation. Foreign OCI graphs are signed at their original OCI root.

content_digest

The portable digest of the package content (the file inventory and documents), independent of how a repository stores it.

representation_digest

The checksum of the stored or transferred representation, such as an archive. It changes when packaging changes, while content_digest does not.

A checksum is never a signature. Use atmos artifacts verify to check signature evidence against your trust policy.

Output​

Every command except show prints a result to stdout and reports progress and status messages on stderr, so output pipes cleanly. The --format flag selects the rendering:

  • text (default for single-artifact commands): aligned name: value lines. Optional values that do not apply are omitted.
  • json and yaml: a structured result with the same field names, whichever format you choose.
  • table, csv, and tsv (additional formats for list and search).

Single-artifact commands share these named result fields:

outcome
created, unchanged, replaced, deleted, read, dry-run, or failed.
ref
The resolved name:version reference.
location
The primary storage location: a path, object key, or registry reference.
resolved_digest, record_digest, content_digest, representation_digest
The digests described above.
size
The payload size in bytes.
lock_scope
The actual write-coordination scope of a mutation: host or repository.

The structured result also carries operation_id, action, repository, requested_ref, duration_ns, and diagnostics, plus command-specific fields. list and search return an artifacts array in which each entry carries repository, ref, name, version, kind, labels, and the digests.

Failures​

A failed command exits with a nonzero status. For a command that runs, --format=json or --format=yaml writes a result to stdout with outcome: failed and an error field. Usage errors, such as invalid argument counts or unknown flags, stop execution without a structured result. In text mode, a failure writes nothing to stdout and the error appears on stderr with hints.

Environment Variables​

Every flag has an ATMOS_ARTIFACTS_ environment variable: ATMOS_ARTIFACTS_REPOSITORY, ATMOS_ARTIFACTS_NAME, ATMOS_ARTIFACTS_VERSION, ATMOS_ARTIFACTS_KIND, ATMOS_ARTIFACTS_FORCE, ATMOS_ARTIFACTS_DRY_RUN, ATMOS_ARTIFACTS_LABELS, ATMOS_ARTIFACTS_README, ATMOS_ARTIFACTS_CHANGELOG, ATMOS_ARTIFACTS_OUTPUT, ATMOS_ARTIFACTS_FROM, ATMOS_ARTIFACTS_TO, ATMOS_ARTIFACTS_REFRESH, ATMOS_ARTIFACTS_FORMAT, ATMOS_ARTIFACTS_YES, ATMOS_ARTIFACTS_INPUT, and ATMOS_ARTIFACTS_EXPECTED_DIGEST. A command-line flag overrides its environment variable, which overrides the default.

Authentication and CI​

Repositories authenticate through Atmos Auth identities named in artifacts.repositories.<alias>.identity, so there is no separate login. Signing can prompt for Sigstore confirmation or identity-provider login. In CI, pass --yes or set ATMOS_ARTIFACTS_YES to accept confirmation; configure the identity provider for unattended authentication. Use --dry-run to validate a publication without contacting a repository or resolving credentials.

CI Summaries and Outputs​

With ci.enabled: true, every atmos artifacts command that runs a repository operation appends one Markdown report to the CI job summary and writes the operation's results as CI output variables. The report covers published, unchanged, replaced, downloaded, copied, deleted, signed, verified, inspected, listed, and failed outcomes.

Each operation gets a row in an overview table and a section with:

  • the outcome, the artifact reference, the repository, and the destination, with credentials and query strings removed so a presigned URL never reaches a summary
  • the size and duration
  • the digests, each labeled by what it identifies: the resolved digest (the OCI manifest or index, or the record for local and S3 repositories), the record digest, the content digest, and the representation digest (a transfer checksum)
  • the lock that coordinated a mutation, stated as the scope that actually applied (host or repository) and what it does and does not exclude
  • for sign and verify, the signature subject, the verified signer identities or key fingerprints, and the verification status

A report never blurs three distinctions. A digest or checksum proves that content is intact, not who published it. A signed artifact has evidence stored for it, but only a verified result means a trusted signer was authenticated. An unchecked result means no trust configuration was supplied, so nothing is claimed.

A failed operation is reported too, so a failed publish shows its error in the summary instead of only in the log. Reporting is best-effort. A template that cannot be loaded or a summary that cannot be written logs a warning and never changes the command's exit status or its JSON and YAML output on stdout. The report is only ever written to the CI summary file or, when no CI provider is detected, to stderr.

The CI output variables use the named outputs of the operation with an artifact_ prefix: artifact_ref, artifact_location, artifact_resolved_digest, artifact_record_digest, artifact_content_digest, artifact_representation_digest, artifact_size, and artifact_outcome. A value the operation did not produce is omitted.

The summary and the outputs follow the existing CI switches: ci.enabled, ci.summary.enabled, ci.output.enabled, and an explicit CI mode such as --ci. With reporting disabled, Atmos makes no extra request to a repository. The report is built from the result the operation already returned. Pull request comments and commit checks are separate, opt-in CI features and are not written by artifact operations. Customize the report with ci.templates.artifacts.

The atmos artifacts catalog subcommands are the exception. They maintain a repository's discovery catalog, do not open a report session, and write neither a CI summary nor CI output variables.

Workflows, Custom Commands, and Hooks​

Every command except the atmos artifacts catalog subcommands also runs as an artifact step in a workflow, a custom command, an embedded script, or a kind: step lifecycle hook. The step calls the same implementation in process, so it needs no atmos artifacts subprocess, and it returns the result that --format=json prints under metadata.artifact, together with the named outputs ref, location, resolved_digest, record_digest, content_digest, representation_digest, size, and outcome. A workflow, a custom command, an embedded script, or a hook writes one CI report for all of its artifact operations after it ends, with retries collapsed to the final attempt.

hooks:
backup-output:
events: [after.terraform.apply]
kind: step
type: artifact
with:
action: publish
source: ./dist
repository: backups
artifact_name: backups/app
version: build-123

Subcommands​