# atmos plugin release

Build, test, package, and publish plugins from a directory or committed inventory.

> ⚠️ Experimental

## Usage

```shell
atmos plugin release [directory] --to <repository> [--sign] [--verify-public]
atmos plugin release --inventory plugins/releases.yaml --check
atmos plugin release --inventory plugins/releases.yaml --sign --yes --verify-public --catalog cloudposse
```

Atmos validates the package, builds every declared platform with bounded concurrency, runs conformance and authored tests
on the current host, packs a temporary OCI layout, and publishes the immutable manifest version.
The temporary layout is removed on success and failure. Cross-built platforms receive static
validation. Tests execute on the current host; testing on additional native runners is optional.

Use this command for the normal source-to-release path. No platform matrix or parallel workflow
configuration is required. CI that separates build credentials from publication can prepare a layout
with `plugin build --all-platforms`, `plugin test`, and `plugin pack`, then pass it to `plugin publish`
in the protected release job.

## Arguments and flags

- **directory**
  Plugin source directory. Defaults to the current directory.
- **--to**
  Destination OCI repository for a directory release, without a tag or digest. Required unless using --check or --inventory. The version comes from plugin.yaml.
- **--inventory**
  Repository-relative committed package inventory. Each package builds from its recorded source in an isolated temporary worktree. Cannot be combined with a positional directory or --to.
- **--check**
  Validate, build, test, and pack without publishing. Cannot be combined with signing, public verification, or catalog publication.
- **--head**
  Committed inventory revision. Defaults to HEAD.
- **--base**
  Revision for independent package version checks. When omitted in CI mode, Atmos uses its CI provider to resolve the comparison base.
- **--catalog**
  Catalog alias or reference to reconcile after inventory publication. Reads accepted inventory from the current default branch on origin. Serialize releases with a shared writer lock.
- **--sign**
  Sign the published multi-platform index using keyless Sigstore signing.
- **--yes, -y**
  Accept transparency-log publication without prompting. Requires --sign.
- **--cosign-version**
  Exact managed Cosign 3 version. Defaults to 3.1.3. Requires --sign when explicitly set.
- **--verify-public**
  Require an existing public GHCR organization package before upload, then verify anonymous access
  to the complete OCI graph. Other registries do not yet have a visibility preflight adapter.
- **--format**
  Publication output format: table (default), json, yaml, csv, or tsv.

## Examples

```shell
atmos plugin release ./my-plugin --to oci://ghcr.io/acme/my-plugin --sign --yes --verify-public
```

Signing and anonymous verification happen after publication. If either fails, the immutable release
remains published and the command fails. Retry with identical bytes; an existing version containing
different bytes is rejected. Inventory releases can reconcile a catalog with `--catalog` after all packages publish successfully. [plugin catalog sync](catalog-sync.mdx) remains available separately.

A simple CI workflow needs two jobs: a read-only check job and a protected release job. Both run
`plugin release --inventory`; the release job rebuilds the recorded sources instead of transferring
artifacts. Hold a global release lock before starting the publishing command. Catalog reconciliation
fetches the current default branch after that lock is acquired, preserving newer accepted versions
even when an older queued workflow runs later.