Skip to main content

Artifacts Configuration

The artifacts section in atmos.yaml defines the repositories that the atmos artifacts commands publish to, read from, and search. Each repository has an alias that you choose, a kind that selects its storage backend, and optional authentication, packaging, write coordination, and signature verification settings.

Experimental

You will learn

  • One list of repositories, addressed by alias, covers local directories, local archives, S3 buckets, OCI registries, and OCI layouts
  • Authentication uses Atmos Auth identities; credentials never appear in repository options
  • Configuration loads without network access, credential resolution, or directory creation
  • Signature verification policy is global and per repository, and a repository can add requirements but never weaken the global ones
  • Write coordination defaults to host scope and can be delegated to a repository that coordinates across hosts

Basic Configuration​

atmos.yaml
artifacts:
repositories:
shared:
kind: oci/registry
identity: registry-publisher
options:
registry: ghcr.io
prefix: acme/atmos
defaults:
metadata:
labels:
team: platform

backups:
kind: aws/s3
identity: backup-writer
packaging: tgz
options:
bucket: acme-artifacts
prefix: atmos
region: us-east-2
tags:
purpose: backup

local:
kind: local/dir
options:
path: .atmos/artifacts

archives:
kind: local/archive
packaging: tgz
permissions: "0600"
options:
path: .atmos/backups

offline:
kind: oci/layout
options:
path: .atmos/oci

The keys under artifacts.repositories (shared, backups, local, archives, offline) are arbitrary aliases. Commands, workflow steps, and hooks select a repository by alias, and a command that needs a repository fails when you omit it. Repository configuration follows standard Atmos deep-merge, so repositories can be defined in imported configuration and overridden per environment.

Repository Fields​

kind (required)

Selects the backend: local/dir, local/archive, aws/s3, oci/registry, or oci/layout.

identity (optional)

Name of an identity under auth.identities. Atmos resolves the identity the first time an operation needs credentials. Listing configuration, validating it, and running --dry-run publications never authenticate. An aws/s3 repository needs an AWS identity, and an oci/registry repository binds the identity to its registry host only.

options (required for every kind)

Backend settings, described below. Credential-shaped keys are rejected.

packaging (optional)

How file payloads are stored: none, tar, tgz, or zip. The supported values and the default depend on the kind.

permissions (optional, local/archive only)

Quoted octal mode of the resulting archive file, for example "0600". The default is "0600". The setting applies to the archive file only, not to its members, S3 access, or OCI access.

defaults.metadata (optional)

A default description and default labels for newly published artifacts. Labels you pass to atmos artifacts publish --labels override matching keys. Labels belong to each published version, not to the repository.

catalog (optional, oci/registry only)

An oci://<registry>/<path>:<tag> reference to the repository's discovery catalog. The catalog must be on the repository's registry host and below its prefix, so it can never direct the repository identity to another host. Listing and searching the collection use the catalog when a registry cannot enumerate its repositories. See Discovery Cache and Catalogs.

verification (optional)

Signature policy for this repository. See Signature Verification.

locking (optional)

Write coordination for this repository. See Write Coordination.

Options by kind​

local/dir and local/archive

path is the destination root. A relative path resolves against the directory of the configuration file that declares it, even when the file is imported. For a remote import, declare the path locally or use an absolute path. key_pattern overrides the path below the root with a Go template over .Name, .Version, .Kind, and .CreatedAt. The pattern is never expanded while configuration loads, must stay inside the root, and must use an extension that agrees with the packaging.

aws/s3

bucket (required), prefix, region, tags (S3 object tags applied to every object, separate from artifact labels), key_pattern, and endpoint for an S3-compatible service. path_style forces path-style addressing, which is the default whenever an endpoint is set.

oci/registry

registry (required) is the registry host with an optional port, and prefix is the collection root below it. Atmos maps a collection and an artifact name onto an OCI repository path.

oci/layout

path is the layout directory, which works offline and in air-gapped environments.

Packaging defaults​

KindSupported packagingDefault
local/dirnonenone
local/archivetar, tgz, ziptgz
aws/s3none, tar, tgz, ziptgz
oci/registry, oci/layouttar, tgz, zip for newly packaged filestgz

Existing OCI content keeps its original media types and graph; the packaging setting does not repackage it.

Signature Verification​

atmos.yaml
artifacts:
verification:
require_signature: true
trusted_identities:
- identity: https://github.com/acme/images/.github/workflows/release.yml@refs/heads/main
issuer: https://token.actions.githubusercontent.com
trusted_keys: []
repositories:
shared:
kind: oci/registry
options:
registry: ghcr.io
prefix: acme/images
verification:
trusted_identities:
- identity: release@acme.example
issuer: https://accounts.google.com

verification is allowed globally and on each repository.

require_signature (optional)

Makes a missing or invalid signature a failure. The default is false for new artifacts. A repository cannot turn off a requirement the global policy sets.

trusted_identities (optional)

Pairs of certificate identity and OIDC issuer. Any one signer in a trust set satisfies that set.

trusted_keys (optional)

Paths to operator-managed public-key files. A relative path resolves against the configuration file that declares it. A public-key signature never satisfies an identity requirement.

When the global policy and a repository both define trust, an artifact must satisfy both sets; they are never merged into a weaker one. Pulling or copying verifies the artifact when policy requires it or supplies trust constraints, before anything is written, and without trust configuration an artifact is reported as unchecked rather than verified. atmos artifacts verify always requires a trusted valid signature. A normal checksum is not a signature, and --force never bypasses verification.

Write Coordination​

Publishing, copying, signing, and deleting take a lock on the reference they change.

atmos.yaml
artifacts:
repositories:
shared:
kind: oci/registry
options:
registry: ghcr.io
prefix: acme/atmos
locking:
required_scope: repository
repository: coordination

coordination:
kind: aws/s3
identity: lock-writer
options:
bucket: acme-artifact-coordination
locking.required_scope (optional)

The minimum guarantee mutations need: host (the default) or repository. A host-scope lock serializes writers on one machine. A repository-scope lock also serializes writers on different machines.

locking.repository (optional)

Takes the lock from another configured repository that provides repository scope, such as an aws/s3 coordinator. The coordinator keeps its own identity and storage root, and the lock is scoped by the collection it protects. Configuration is rejected when the coordinator does not exist, when delegation forms a cycle, or when the coordinator cannot provide the required scope.

An aws/s3 repository coordinates across hosts by itself. Local and OCI repositories provide host scope on their own; an OCI tag is not a distributed lease, so use locking.repository for cross-host exclusion. S3 lock claims never expire, so a crashed writer leaves a diagnostic naming the claim to remove after you confirm that the writer has stopped. The lock_scope field of every mutation result reports the scope that actually coordinated it.

Discovery Cache and Catalogs​

atmos artifacts list and atmos artifacts search read repositories directly, and cache the listing of remote repositories (aws/s3 and oci/registry) for fifteen minutes. Local directories, archives, and OCI layouts are listed live every time.

The cache lives in the Atmos cache directory under artifacts/discovery, as one private snapshot file per repository source. Each snapshot is scoped by your authentication configuration, the authentication realm, and the identity bound to each repository, never by credential values, so a different realm or identity never reuses another's snapshot. A refresh replaces a snapshot atomically only after it completed. Pass --refresh to revalidate a source before the fifteen minutes pass. A refresh reuses the metadata of references whose digest is unchanged, and removes a reference that disappeared only after a complete refresh.

With plugins.policy.offline: true, discovery is offline: it serves existing snapshots of any age, makes no registry or bucket request, and fails with an offline error when a snapshot is missing or corrupt or when --refresh is requested. Current policy is checked on every read, including reads of a cached snapshot, and a cached listing never proves that a payload is still available.

A registry cannot be enumerated portably. Listing a whole oci/registry collection uses the registry's repository catalog scoped to prefix, or the repository's catalog when one is configured. Listing the versions of one name (atmos artifacts list <name>) needs neither. A collection that cannot be enumerated fails with an unsupported-capability error instead of returning an empty list.

atmos.yaml
artifacts:
repositories:
shared:
kind: oci/registry
identity: registry-reader
options:
registry: ghcr.io
prefix: acme/atmos
catalog: oci://ghcr.io/acme/atmos/catalog:stable

A catalog is a maintained discovery snapshot, not a trust grant. Publishing, signing, or deleting an artifact never edits a catalog; maintain it with atmos artifacts catalog. Every catalog entry must be bound to the repository path it is configured on.

CI Reporting​

Artifact operations report to CI through the same switches as every other Atmos feature, and add no artifact-specific reporting keys. The report is a Markdown job summary and a set of CI output variables:

ci.enabled
The master switch. Without it, artifact operations write no summary and no CI outputs.
ci.summary.enabled
Appends one report per command, workflow, custom command, or hook to the job summary. Defaults to true when ci.enabled is set.
ci.output.enabled
Writes the artifact_* output variables. Defaults to true when ci.enabled is set.
ci.templates.artifacts
Replaces the built-in report templates. See CI templates.

Pull request comments (ci.comments) and commit checks (ci.checks) are not written by artifact operations. With reporting disabled, no operation makes an extra metadata or evidence request. See CI summaries and outputs for what a report contains.

Environment Variables​

The flags of the atmos artifacts commands read ATMOS_ARTIFACTS_* environment variables, such as ATMOS_ARTIFACTS_REPOSITORY and ATMOS_ARTIFACTS_FORMAT. Command-line flags override environment variables. See the command reference for each variable.