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.
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
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, oroci/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-runpublications never authenticate. Anaws/s3repository needs an AWS identity, and anoci/registryrepository 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, orzip. The supported values and the default depend on the kind.permissions(optional,local/archiveonly)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
descriptionand defaultlabelsfor newly published artifacts. Labels you pass toatmos artifacts publish --labelsoverride matching keys. Labels belong to each published version, not to the repository.catalog(optional,oci/registryonly)An
oci://<registry>/<path>:<tag>reference to the repository's discovery catalog. The catalog must be on the repository's registry host and below itsprefix, 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/dirandlocal/archivepathis 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_patternoverrides 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/s3bucket(required),prefix,region,tags(S3 object tags applied to every object, separate from artifact labels),key_pattern, andendpointfor an S3-compatible service.path_styleforces path-style addressing, which is the default whenever anendpointis set.oci/registryregistry(required) is the registry host with an optional port, andprefixis the collection root below it. Atmos maps a collection and an artifact name onto an OCI repository path.oci/layoutpathis the layout directory, which works offline and in air-gapped environments.
Packaging defaults
| Kind | Supported packaging | Default |
|---|---|---|
local/dir | none | none |
local/archive | tar, tgz, zip | tgz |
aws/s3 | none, tar, tgz, zip | tgz |
oci/registry, oci/layout | tar, tgz, zip for newly packaged files | tgz |
Existing OCI content keeps its original media types and graph; the packaging setting does not repackage it.
Signature Verification
verification is allowed globally and on each repository.
require_signature(optional)Makes a missing or invalid signature a failure. The default is
falsefor new artifacts. A repository cannot turn off a requirement the global policy sets.trusted_identities(optional)Pairs of certificate
identityand OIDCissuer. 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.
locking.required_scope(optional)The minimum guarantee mutations need:
host(the default) orrepository. 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/s3coordinator. 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.
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
truewhenci.enabledis set. ci.output.enabled- Writes the
artifact_*output variables. Defaults totruewhenci.enabledis 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.
Related
atmos artifacts- publish, pull, copy, inspect, list, search, delete, sign, and verifyatmos artifacts catalog- build and maintain a repository's discovery catalog- Authentication - identities referenced by
identity