Skip to main content

atmos plugin release plan

Plan independently versioned plugin releases from committed manifests.
Experimental
atmos plugin release plan --help

Usage​

atmos plugin release plan --inventory plugins/releases.yaml [--base origin/main] --format json

The planner reads committed Git content and returns deterministic packages.include and build.include JSON matrices. Each package has its own manifest version, OCI repository, and exact source commit. Local uncommitted edits are not part of a release plan.

With CI output enabled (ci.enabled: true and ci.output.enabled: true), successful plans also export packages and build as compact JSON matrices through Atmos's CI provider. On GitHub Actions, these become step outputs through GITHUB_OUTPUT, so workflows can use ${{ steps.plan.outputs.packages }} directly without jq or shell output-file handling. JSON is still printed to stdout. Set ci.output.enabled: false to disable these exports.

With --base, or the comparison revision resolved by Atmos's CI provider when CI mode is enabled, changes to a package or its declared shared inputs require a version increase relative to the base. Versions cannot decrease. Inventory changes affect the packages whose entries or platform runner mappings changed; adding an unrelated package does not force existing package bumps. Outside CI mode, a plan without --base lists accepted versions for release retries; immutable publication still rejects different bytes for an existing version.

Arguments and flags​

--inventory
Repository-relative YAML inventory. Defaults to plugins/releases.yaml. Also ATMOS_PLUGIN_RELEASE_INVENTORY.
--head
Committed Git revision to plan. Defaults to HEAD. Also ATMOS_PLUGIN_RELEASE_HEAD.
--base
Revision for independent version checks. Overrides automatic CI base detection. Also ATMOS_PLUGIN_RELEASE_BASE.
--format
Output format. Currently json only, which is also the default.

Examples​

Declare repositories and runner mappings explicitly; Atmos does not impose a publisher namespace or CI runner names:

packages:
  repo-tools:
    path: plugins/repo-tools
    repository: oci://ghcr.io/acme/repo-tools
    inputs:
      - sdk/**
      - go.mod

Cross-building on one host needs no runner mappings. Projects choosing distributed native tests may add a runners mapping covering every declared platform; incomplete mappings are rejected. Platform variants remain part of the platform key. Each build entry includes its executable path and artifact name, plus a runner when configured. The source is the latest commit affecting the package, shared inputs, or inventory, so unrelated repository commits do not change the source used to rebuild an existing package.

atmos plugin release plan --base origin/main > release-plan.json

For catalog reconciliation, run catalog sync directly against the committed inventory. It does not consume a release plan or require CI runner mappings.