Skip to main content

Plugins

Declare the native plugins a project uses, where to discover them, and which releases Atmos may install. Declarations and the release lock are committed with the project, so every machine and CI run restores the same reviewed release.

Experimental

Usage​

atmos.yaml
plugins:
  max_concurrency: 4
  packages:
    corporate:
      source: oci://registry.example.com/team/oidc
      version: "^0.1.0"
      timeout: 5m
  registries:
    team:
      host: registry.example.com
      identity: registry-reader
      repositories:
        - oci://registry.example.com/team/oidc
  discovery:
    cache_ttl: 15m
  policy:
    require_signature: true
    trusted_publishers:
      - publisher: acme
        identity: "https://github.com/acme/atmos-oidc/.github/workflows/release.yaml@refs/tags/*"
        issuer: "https://token.actions.githubusercontent.com"

Manage the declarations with atmos plugin install, update, remove, and registry add. These commands edit only the keys they own and keep your comments and formatting. The selected release is recorded in .atmos.plugins.lock.yaml, next to atmos.yaml.

plugins​

max_concurrency
Maximum parallel downloads and discovery requests. Defaults to 4; 1 installs sequentially. Negative values are invalid.
cache_dir
Storage root for downloaded releases and discovery metadata. Defaults to the Atmos XDG data and cache directories.

plugins.packages.<alias>​

source
OCI repository of the release, such as oci://registry.example.com/team/oidc. Required while the package is enabled, unless path is set.
version
Semantic version constraint. Required while the package is enabled, unless path is set. plugin install records ^1.4.2 (or ^0.1.0 for a 0.x release, and an exact version for a pre-release) when you install a new package without --version.
path
Directory of a locally built plugin: the folder that holds plugin.yaml and the executable it names. A relative path is relative to the project directory (the directory of the root atmos.yaml); an absolute path is used as is. When set, it wins over source and version, which stay valid and apply again when path is not set. Atmos reads the manifest and the executable from the directory on every activation, so rebuilding is enough; the package has no lock entry, is not cached, and is not checked for a signature or version. Set it in a profile of your own so the local build applies only while that profile is active. plugin install skips the package, install --frozen refuses while it is set, and plugin list reports state path. Atmos prints one warning per alias when it starts the plugin.
enabled
false keeps the declaration but skips installation and activation, including a configured path. Source and version are not required while disabled.
timeout
Positive Go duration, such as 30s or 5m, that bounds every call into the plugin. Omit for no deadline.
command
Command export that plugin run starts when the package exports several.
config
Settings passed to the plugin command, validated against the command's schema when it declares one.
scope
Only project is supported.

Packages install automatically only when a command needs one of their exports, and CI refuses to create a lock entry that is not already committed. See automatic installation.

plugins.registries.<name>​

host
Registry authority used for authentication, independent of discovery. Inferred from catalog or repositories when omitted. All sources must share one host.
identity
Name of an auth.identities entry that authenticates to the host. An identity binding is exclusive: a failure does not fall back to Docker or ambient credentials.
auth
Only docker (the shared Docker and stored-credential chain) is supported. registry add writes it when no identity is set.
catalog
Optional OCI reference to a curated discovery catalog.
repositories
OCI repositories that Atmos indexes directly, without a catalog.

The order Atmos uses to pick credentials is in credential precedence.

plugins.discovery​

cache_ttl
How long discovery metadata stays fresh, as a nonnegative Go duration. Defaults to 15m; 0 revalidates on every online search.

plugins.policy​

require_signature
Admit only releases signed by a trusted publisher. It governs released packages; a package that sets path has no signature and is governed by plugin policy rules over origin: development and input.path. Needs at least one entry in trusted_publishers in some loaded configuration file. Later files cannot turn it off.
trusted_publishers
List of publisher (the namespace before / in the package name), identity (the signer's certificate subject; * is the only wildcard), and issuer (exact). A non-empty list enables enforcement.
offline
Forbid registry access. Installation, restoration, and corrupt-cache repair then need an explicit --from-layout, and discovery serves the cache even when stale.

For signature setup and offline verification, see trusted publishers. To restrict registries, package names, and local builds for the whole organization, use plugin policies. For the development loop that path enables, see the plugin development tutorial.