Skip to main content

atmos artifacts catalog publish

Publish a catalog snapshot to the catalog configured on a repository. The command refuses to overwrite newer catalog metadata with a stale snapshot.

Experimental

Usage​

atmos artifacts catalog publish <file> --repository=<alias> [flags]

Examples​

# Publish a built snapshot
atmos artifacts catalog publish catalog.json --repository=shared

# Publish only if the catalog is still the one the snapshot was built from
atmos artifacts catalog publish catalog.json --repository=shared --expected-digest=sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Behavior​

Publish replaces the catalog's entries with the snapshot. Before it writes, it checks that the repository has a catalog configured, that every entry is bound to the repository path, and that the snapshot's revision equals the published catalog's revision. With --expected-digest it also checks the catalog's manifest digest. After a successful write the revision increases by one.

The write takes the repository's lock when the repository provides one, reads the latest catalog inside the lock, and checks the previous reference immediately before it moves the tag. Run only one catalog writer at a time. See One writer at a time.

Arguments​

file (required)

A catalog snapshot written by atmos artifacts catalog build, in JSON or YAML.

Flags​

--repository, -r (required)

Configured repository alias. Its catalog setting selects where the catalog is published. Environment variable: ATMOS_ARTIFACTS_REPOSITORY

--expected-digest (optional)

Require the published catalog to have this manifest digest. Use the base_digest that build printed. Environment variable: ATMOS_ARTIFACTS_EXPECTED_DIGEST

--format (optional)

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

Output​

Stdout carries catalog, the new digest, the previous_digest, revision, listed, added, and lock_scope.

Errors​

Catalog not configured
The repository has no catalog. Nothing is written.
Catalog changed
The published catalog has a different revision or digest than the snapshot expects. Rebuild the snapshot from the latest catalog.
Location outside the repository
An entry names another registry, prefix, or path than the repository. Nothing is written.

Every failure exits with a nonzero status.

Related​