# atmos plugin catalog sync

Reconcile verified plugin releases into a catalog in one publication.

> ⚠️ Experimental

## Usage

```shell
atmos plugin catalog sync <catalog> [--inventory plugins/releases.yaml] [--head HEAD] [--skip-missing] [--verify-public]
```

Atmos reads the committed package inventory and each package’s committed manifest to select
release names, versions, and OCI repositories. It verifies those releases in OCI, merges their
metadata into the current catalog, and publishes one catalog revision. Earlier versions and existing listing/yank metadata
are preserved. A missing catalog can be created; an immutable version cannot be replaced with a
different digest.

Serialize catalog writers externally. Acquire the lock before reading the latest accepted source
and running sync. Revision and digest rechecks reject already-stale updates, but OCI
publication is not atomic compare-and-swap and does not replace a workflow concurrency lock.

The inventory uses the same package declarations as [release planning](./release-plan.mdx),
but catalog sync does not require runner mappings, compute build matrices, inspect build history,
or check version bumps. It does not build or publish plugin packages. Package versions come from
`plugin.yaml` at the selected revision; catalog metadata is extracted from verified OCI artifacts.

## Arguments and flags

- **catalog**
  A configured catalog alias or an explicit oci:// catalog reference.
- **--inventory**
  Repository-relative YAML package inventory. Defaults to plugins/releases.yaml.
- **--head**
  Committed Git revision containing the inventory and manifests. Defaults to HEAD.
  Uncommitted working-tree edits are ignored.
- **--skip-missing**
  Skip release references that return not found, allowing another accepted package to finish publishing.
  Authentication, integrity, and other failures still fail the operation.
- **--verify-public**
  Require public GHCR organization packages, verify release content anonymously, and verify the
  published catalog anonymously.

## Examples

Run inside the catalog writer's serialized job, after checking out current accepted source:

```shell
atmos plugin catalog sync cloudposse --inventory plugins/releases.yaml --skip-missing --verify-public
```

A catalog-only inventory can omit build inputs and runner mappings:

```yaml
packages:
  repo-tools:
    path: plugins/repo-tools
    repository: oci://ghcr.io/acme/repo-tools
```

The referenced `plugins/repo-tools/plugin.yaml` must be committed at the selected revision.

Publication and catalog reconciliation are independent operations. A catalog failure does not
remove a successfully published immutable release. Rerun reconciliation after resolving the failure.