The Problem​

CI logs are the system of record for infrastructure changes, but they're not built for review. Finding "which command ran against which stack, and did it succeed" means opening job after job and reading output meant for a terminal, not a dashboard. Resource usage — how long a command actually took, how much memory it needed — was never captured at all, so slow pipelines were diagnosed by guesswork.

The Fix​

When Atmos runs in a recognized CI environment with Atmos Pro configured, it now reports a lightweight execution record for every command automatically — no extra setup beyond what you already have. The record covers the Atmos version, the command and its exit code, and how long it took to run.

Most commands report this in the background and never slow anything down. terraform plan, terraform apply, and describe affected wait briefly to confirm the record made it to Atmos Pro before the command finishes, so a pipeline never reports success for a run Atmos Pro never saw — and if delivery is slow or fails, the command still completes; it only logs a warning.

How to Use It​

There's nothing to turn on. If Atmos Pro is already configured and Atmos is running in CI, execution records start flowing immediately.

The only knob is how long a critical command (terraform plan, terraform apply, describe affected) is willing to wait for Atmos Pro to confirm it received the record before moving on — 10 seconds by default:

settings:
  pro:
    exec:
      sync_timeout_seconds: 20

Raise it if your network to Atmos Pro is slow; the default already covers most setups.

Get Involved​

This is the foundation for richer execution history in Atmos Pro — itemized resource changes from terraform plan/apply are next. Tell us what you'd want to see in an execution's timeline. Open an issue or start a discussion at github.com/cloudposse/atmos.

The Problem​

Atmos could already generate backend.tf.json for an azurerm backend and read its state in-process — but it couldn't create the backend. Turn on backend auto-provisioning against an azurerm backend and nothing happened; it silently skipped, because provisioning only knew how to make S3 buckets. So every new subscription hit the same chicken-and-egg: you need remote state to run Terraform, but you need something other than Terraform to create that remote state first.

The workaround was a bespoke storage-account component that runs on local state, then migrates its own state into the account it just created. It works, but it's ceremony every team re-invents — and it's exactly the friction AWS users don't have.

The Fix​

Atmos now provisions azurerm backends automatically, the same way it does for S3. Point a component at an azurerm backend, enable provisioning, and Atmos creates what's missing — the resource group, the storage account, and the container — with secure defaults, before terraform init runs.

Everything is created with opinionated, hardcoded best practices:

• TLS 1.2 minimum and HTTPS-only traffic
• Public blob access blocked; the state container is private
• Blob versioning enabled — the direct analog of S3 versioning, so every state write is recoverable
• Soft delete (blob + container) with 30-day retention as a safety net
• Entra ID hardening: when your backend sets use_azuread_auth: true, the storage account is created with shared-key access disabled — no account keys to leak

And one thing Atmos deliberately does not create: a lock table. On Azure, state locking is built into Blob Storage — the azurerm backend takes an exclusive blob lease on the state blob during each operation, so concurrent runs are serialized with no extra resource. (On AWS that role is played by a DynamoDB table or native S3 lockfiles; on Azure there's simply nothing to provision.)

How to Use It​

Add provision.backend.enabled: true to a component that uses an azurerm backend:

components:
  terraform:
    vpc:
      auth:
        providers:
          azure:
            type: azure/interactive
            identity: platform

      backend_type: azurerm
      backend:
        resource_group_name: rg-tfstate-cus
        storage_account_name: stexampletfstateplatformcus
        container_name: tfstate
        key: vpc.terraform.tfstate
        use_azuread_auth: true

      provision:
        backend:
          enabled: true

Then run Terraform as usual:

atmos terraform apply vpc -s platform-cus
# Backend resource group, storage account, and container are created if missing, then init/apply proceed.

That's it. Atmos checks whether the backend is fully provisioned, creates only what's missing, and continues. It's idempotent — safe to leave enabled and safe to re-run.

A few things worth knowing:

• You don't put location in the backend block. It isn't a valid azurerm backend argument, so Atmos takes the region from your active Azure identity — or, if the resource group already exists, from the group itself. Pre-create the resource group and you don't need to configure a location at all.
• Subscription comes from backend.subscription_id if set, otherwise from your active Azure identity.
• It composes with inheritance. Enable provisioning once at the org or environment level and override per component — on in dev/qa, off in prod where state storage is module-managed.

Managing the backend explicitly​

The same lifecycle commands that work for S3 now work for azurerm:

# Create the backend explicitly (e.g. in a CI bootstrap stage)
atmos terraform backend create vpc -s platform-cus

# Tear it down (deletes the storage account and all state in it — resource group is preserved)
atmos terraform backend delete vpc -s platform-cus --force

Deletion always requires --force, and it removes the storage account (and therefore every state file in it, just as deleting an S3 bucket does), while leaving the resource group in place.

Not for Production As-Is​

Like the S3 provisioner, this is built for fast, secure bootstrapping — dev, test, CI, and cold-starts — not to replace a production-grade module. It doesn't set up customer-managed keys, private endpoints, network ACLs, geo/zone redundancy, or lifecycle policies. When you're ready to harden, import the resource group, storage account, and container into a managed module (such as Azure/avm-res-storage-storageaccount) and keep using the same backend — no state migration needed, because the account keeps its name and contents. You can even leave provisioning enabled; Atmos detects the resources exist and skips.

Get Involved​

Give it a try on your Azure subscriptions and let us know how it goes. Questions or ideas? Start a thread in GitHub Discussions, or open an issue in the issue tracker.

The Problem​

Official Atmos skills (atmos-terraform, atmos-stacks, and the rest of the catalog) are embedded directly in the atmos binary. Installing one by name copies its SKILL.md and supporting files to ~/.atmos/skills/ at that point in time. If a later atmos release bundles an improved version of that skill, nothing tells you, and nothing refreshes your local copy — the only way to pick it up was atmos ai skill install <name> --force, applied on faith, one skill at a time, with no way to check first whether anything had actually changed.

atmos ai skill list --detailed already surfaced an "update available" hint when an installed skill's version drifted from the catalog. There was no command that acted on it.

The Fix​

atmos ai skill update closes that gap. It compares each installed bundled skill's recorded version against the catalog embedded in the running binary and reinstalls only the ones that are actually outdated — skills already at the current version are left untouched.

Run it with no arguments to refresh every installed bundled skill that has an update available (a single confirmation, not one per skill), or name one skill to update just that one. Skills that are already current report "already up to date" and nothing is rewritten, so it's safe to run atmos ai skill update repeatedly, including as a habit after every atmos upgrade.

An outdated skill is reinstalled the same way atmos ai skill install <name> --force would install it, so --client, --scope, --global, --all-clients, and --path all work exactly as they do on install.

Skills installed from a GitHub repository aren't covered yet — there's no cheap way to check whether a git-sourced skill's upstream has moved without re-fetching it. Run atmos ai skill install <source> --force to refresh one of those manually.

How to Use It​

# Update a single bundled skill if a newer version is available.
atmos ai skill update atmos-terraform

# Update every installed bundled skill that has an update available.
atmos ai skill update

# Skip the confirmation prompt (for automation).
atmos ai skill update --yes

# Update and redistribute to a specific AI client.
atmos ai skill update atmos-terraform --client vscode

Get Involved​

Read the atmos ai skill documentation for the full command reference. To share feedback or request an improvement, open an issue.

The Problem​

The atmos ai skill list command already listed every official skill, showing each skill's name, source, and install status. Add --detailed, and it also showed a one-line description. But no view showed a skill's full instructions -- the actual content that teaches the AI its domain knowledge.

To read that content, you had two options. Install the skill first. Or open the Atmos repository on GitHub and find the right SKILL.md file. Neither option let you compare skills quickly. Neither option gave an AI agent a direct way to fetch and read a skill's content on its own.

The Fix​

The Agent Skills Directory lists every skill with its full content. Open the directory. Search by name, description, or category. Click a skill to read its complete instructions -- no install step required. Add a new skill to the Atmos repository, and it appears in the directory automatically.

Each skill's page also has a raw Markdown version. Add .md to the page's URL. This is the same convention the rest of the Atmos docs site uses. An AI agent can fetch this URL directly and read the skill's content.

Each skill's page also has a "Copy as Markdown" button. Use it to copy the skill's full content. Paste it into a chat session, or review it, before you install anything.

The atmos ai skill list command also gained a --format flag and a Category column, so the same categorization shown in the directory is available from the CLI.

How to Use It​

Browse and search the directory at atmos.tools/ai/skills. Or fetch a skill's content directly:

# Raw Markdown for one skill - readable by a human, fetchable by an agent
skill_name=atmos-ai
curl "https://atmos.tools/ai/skills/${skill_name}.md"

# Table view, now with a Category column
atmos ai skill list

# Machine-readable output for scripting
atmos ai skill list --format=json
atmos ai skill list --format=yaml

Get Involved​

See the Agent Skills guide to learn how skills are structured. It also explains how to contribute one. Share skill ideas and contributions in the Atmos community.

The Problem​

Delivering rendered Kubernetes manifests to a Git deployment repository (the source Argo CD or Flux reconciles) always wrote them as a directory — one generated file per manifest, no way to land a single file under an exact, caller-chosen name. That's a fine default for a directory of standalone resources, but it can't produce kustomization.yaml, so it couldn't support this pattern at all. Separately, Kustomize's own Kustomization and Component config objects don't have a metadata.name in the real Kustomize schema — they're local input to the kustomize build tool, not Kubernetes API resources — but Atmos's manifest validator required one anyway, rejecting perfectly valid Kustomize files.

The Fix​

A git provision target's path can now be an exact single-file destination, not just a directory. Set split: false to merge every rendered manifest into one file written at that path; leave it unset and Atmos infers the right mode from whether the path looks like a manifest filename (.yaml, .yml, or .json). Every existing configuration keeps its current directory behavior unchanged.

Atmos also now recognizes Kustomize's own Kustomization and Component kinds and no longer requires a metadata.name on them — matching Kustomize's own validation, not an opinion Atmos invented. For anything else, a new validate: false component setting opts out of Atmos's structural checks entirely.

How to Use It​

components:
  kubernetes:
    cert-manager-patch:
      provision:
        targets:
          deployment-repo:
            kind: git
            repository: deployments
            path: "kustomize/overlays/{{ .vars.environment }}/kustomization.yaml"
            commit:
              message: "Render manifests for {{ .vars.environment }}"
      manifests:
        - apiVersion: kustomize.config.k8s.io/v1alpha1
          kind: Component
          patches:
            - target:
                kind: ClusterIssuer
                name: letsencrypt-dns
              patch: |
                - op: add
                  path: /spec/acme/solvers
                  value:
                    - dns01:
                        route53:
                          region: "{{ .vars.aws_region }}"
                          hostedZoneID: "{{ atmos.Resolve \"!terraform.state route53 public_zone_id\" }}"

atmos kubernetes deploy cert-manager-patch -s plat-ue2-dev --target=deployment-repo

No split is set here — the path ends in kustomization.yaml, so Atmos writes it as a single file automatically. No metadata.name is needed on the Component object either. The real Kustomize overlay then includes the generated file as a remote component, so the Terraform-derived value flows through on every deploy without anyone touching the overlay by hand. See Generating a Kustomize component for GitOps for the full walkthrough.

Get Involved​

Try delivering a Kustomize component or patch through a git provision target in your own GitOps repo. Tell us what's missing — pull-request publishing for the git target, support for other Kustomize-only object kinds, or something else — by opening an issue at github.com/cloudposse/atmos.

The Problem​

Atmos workflows and custom commands already covered most of what a task runner needs: steps, templating, conditionals, parallel execution. But a handful of real gaps kept people from fully retiring go-task:

• No dependency ordering between named commands or workflows. You could make steps within one command run in parallel, but you couldn't say "run build before test and lint, and don't run build twice just because two things depend on it."
• No up-to-date checking. go-task's sources:/generates: skip a task when nothing has changed. Atmos had nothing like it — every step ran every time, even a slow compile step whose inputs hadn't changed since the last successful run.
• No continue-on-error. A single failing step stopped everything downstream, even for steps — like a linter — where you'd rather collect every result and report at the end.
• No precondition shortcut. Skipping an install step when a tool is already on PATH meant hand-rolling a shell check.
• Custom commands couldn't use parallel/matrix at all. The migration guide's own suggested workaround — wrap dependents in a parallel step with needs: — silently failed on custom commands; it only worked in workflows.

The Fix​

Custom commands and workflows now cover all of it, using the same when:/CEL condition engine and scheduler Atmos already had — no second, bespoke mechanism bolted on.

Dependencies between commands and workflows​

commands:
  - name: build
    steps: [...]
  - name: test
    dependencies:
      commands: [build]
    steps: [...]
  - name: lint
    dependencies:
      commands: [build]
    steps: [...]
  - name: release
    dependencies:
      commands: [test, lint]
    steps: [...]

build is declared as a dependency of both test and lint, but it only runs once — the graph dedups identical dependency invocations automatically. Dependencies run concurrently by default. Need the same command with different inputs? Parameterize it:

dependencies:
  commands:
    - name: build
      flags: { env: dev }
    - name: build
      flags: { env: prod }

Both invocations run — different parameters mean different graph nodes. Workflows get the same dependencies.workflows, including cross-file references via file:.

Skip steps that are already up to date​

steps:
  - name: compile
    inputs:
      sources: ["cmd/**/*.go", "go.sum"]
    artifacts:
      paths: ["bin/handler"]
    command: go build -o bin/handler ./cmd/handler

No extra configuration needed — declaring inputs/artifacts alone means "skip this step unless sources changed since the last successful run." Run it twice in a row and the second run skips entirely. Power users can reference the underlying facts directly (checksum.changed, timestamp.changed, or the raw per-file sources/artifacts records) for custom logic.

Skip a step when a tool is already installed​

steps:
  - name: install-stringer
    preconditions:
      tools: ["stringer"]
    command: go install golang.org/x/tools/cmd/stringer@latest

Resolved via Go's exec.LookPath — no shell, so it works identically on Linux, macOS, and Windows.

Continue past a failing step​

steps:
  - type: shell
    command: golangci-lint run ./...
    continue: always
  - type: atmos
    command: terraform apply vpc -auto-approve

continue: always mirrors GitHub Actions' continue-on-error: the step's own failure is still visible, later steps still run, and the overall exit status is unaffected.

parallel/matrix now works in custom commands​

The exact recipe that used to only work in workflows now works identically in custom commands:

commands:
  - name: release
    steps:
      - type: parallel
        steps:
          - name: test
            command: go test ./...
          - name: lint
            needs: [test]
            command: golangci-lint run ./...

Also Shipped​

A handful of smaller gaps closed alongside the above:

• platforms via when: — when: "os == 'darwin'" instead of a dedicated field, reusing facts already available everywhere else when: is.
• Native command aliases — aliases: [dep, d] on a custom command, registered in-process, distinct from the top-level subprocess-redirect aliases: config.
• internal: true — hide a command from atmos help/atmos list while leaving it fully invocable, for commands meant only to be run as someone else's dependency.
• values: on flags and arguments — restrict a flag to a fixed set of choices, with static validation and an interactive picker when a required value is missing.

How to Use It​

All of this is available today in custom commands and workflows — no flags to enable, no config migration required. See dependencies, inputs, artifacts, preconditions, and continue for the full field references, or the Alternatives page for how Atmos compares to go-task more broadly.

Get Involved​

If you're still running go-task alongside Atmos for one of these reasons, we'd like to hear about it — open a discussion on GitHub Discussions and tell us what's still missing.

What Changed​

Aqua's registry defines several package types for downloading tools. Atmos previously supported only two:

• github_release — assets attached to a GitHub Release
• http — arbitrary HTTP(S) URLs

Two more are now supported:

• github_archive — the auto-generated source tarball produced by GitHub for any tag, downloaded from github.com/{owner}/{repo}/archive/refs/tags/{version}.tar.gz. Always .tar.gz, regardless of the format field.
• github_content — a single file from a GitHub repo at a tag, downloaded from raw.githubusercontent.com/{owner}/{repo}/{version}/{path}. The required path field points to the file inside the repo.

Both implementations match upstream aquaproj/aqua exactly. For github_archive, the asset, url, format, and format_overrides fields are intentionally ignored (Aqua hardcodes tar.gz and the URL pattern). For github_content, the same fields are ignored — only repo_owner, repo_name, and path are used.

Before this release, any Aqua registry entry using either type failed with unsupported tool type: .... Those entries now resolve correctly.

How to Use It​

github_archive​

For a tool that ships its binary as a script inside its source tree — such as adr-tools:

packages:
  - type: github_archive
    repo_owner: npryce
    repo_name: adr-tools
    files:
      - name: adr
        src: adr-tools-{{trimV .Version}}/src/adr

The {{trimV .Version}} template expands to match GitHub's archive root directory (e.g., adr-tools-3.0.0/ for version v3.0.0), so files[].src points to the file inside the extracted archive.

github_content​

For a tool that ships as a single raw file in a repo — such as kubens from ahmetb/kubectx:

packages:
  - type: github_content
    repo_owner: ahmetb
    repo_name: kubectx
    path: kubens

The download URL becomes https://raw.githubusercontent.com/ahmetb/kubectx/{version}/kubens. No archive extraction is involved — the file is downloaded directly.

Why This Matters​

Aqua's upstream registry has hundreds of entries that use these two types — tfenv, tgswitch, adr-tools, kubectx, kubens, and many one-binary shell-script projects. Until now, those entries were dead in Atmos. Adding these two package types unblocks all of them without registry-level changes: pull the Aqua registry entry as-is and it just works.

The Aqua-compatible build/install types (go_install, go_build_install, cargo) remain unsupported — they require invoking a language toolchain at install time rather than downloading an artifact, which is a different installation model. A follow-up issue tracks that work.

Get Involved​

Atmos is open source on GitHub. File issues or open PRs if you hit any tools the registry can't resolve.

Why This Matters​

Device code is getting blocked: Microsoft-managed Conditional Access policies now block the device code flow in many tenants (error AADSTS530035), so azure/device-code fails there. The interactive browser flow carries full Conditional Access context, so it keeps working.

One command instead of two: azure/cli requires a pre-existing az login session. With azure/interactive, atmos auth login is the only command you run.

Silent repeat logins: Atmos tries silent acquisition from the persisted MSAL cache first. Refresh tokens make repeat logins silent — no browser after the first sign-in.

Drop-in for az login: Atmos writes the Azure CLI-compatible cache files (MSAL token cache and azureProfile.json), so after atmos auth login the az CLI works without ever running az login. Guest/B2B users are handled correctly using the real MSAL home account ID.

How to Use It​

auth:
  providers:
    azure-browser:
      kind: azure/interactive
      spec:
        tenant_id: "12345678-1234-1234-1234-123456789012"
        subscription_id: "87654321-4321-4321-4321-210987654321"
        location: eastus

  identities:
    azure-dev:
      default: true
      kind: azure/subscription
      via:
        provider: azure-browser
      principal:
        subscription_id: "87654321-4321-4321-4321-210987654321"
        location: eastus

Then authenticate:

atmos auth login

Atmos opens your default browser for sign-in (with MFA if configured), acquires Management, Graph, and Key Vault tokens, and caches them for azurerm, azuread, and azapi. Chain identities via azure/subscription exactly like the other Azure providers.

The spec shape is identical to azure/device-code: tenant_id (required), plus optional subscription_id, location, client_id (defaults to the Azure CLI public client), and cloud_environment (public, usgovernment, or china).

The flow requires an interactive terminal and a browser. For headless environments and CI/CD, keep using azure/oidc; where a browser can't be opened (e.g., SSH sessions), azure/device-code remains available.

Get Involved​

• Read the provider documentation and the Azure Authentication tutorial
• Report issues on GitHub

The Problem​

A kind: store hook reads a Terraform output and writes it to a configured store, so other components can read it back later with !store or !store.get. Before this change, the supported lifecycle events did not include output or refresh. Nothing fired when you just wanted to read a value from infrastructure that already exists.

That gap matters most for the infrastructure you're least likely to touch again soon: a production VPC someone applied by hand two years ago, or a reference architecture deployed before your organization adopted hooks at all. Backfilling a store from that infrastructure meant either re-running apply against something that didn't need to change, or writing the value into the store yourself, outside Atmos.

The Fix​

Atmos now fires lifecycle hooks around atmos terraform output and atmos terraform refresh, the same way it already does for plan, apply, and test. A kind: store hook (or a type: store step run through the kind: step bridge) can bind to after.terraform.output instead of, or alongside, after.terraform.apply:

hooks:
  backfill:
    events: [after.terraform.output]
    kind: store
    name: prod/ssm
    outputs:
      vpc_id: .id

Running atmos terraform output vpc -s prod now reads the current state and writes vpc_id into the store — no apply required. before/after.terraform.refresh events fire the same way around atmos terraform refresh, for hooks that care about reconciling state with the real infrastructure rather than just reading it.

How to Use It​

Scope a store hook to after.terraform.output to backfill values from infrastructure that's already running:

hooks:
  outputs:
    events: [after.terraform.output]
    kind: store
    name: prod/ssm
    outputs:
      vpc_id: .id
      private_subnet_ids: .private_subnet_ids

atmos terraform output vpc -s prod

Keep an existing after.terraform.apply hook untouched, or list both events on the same hook so it fires on either command:

hooks:
  outputs:
    events: [after.terraform.apply, after.terraform.output]
    kind: store
    name: prod/ssm
    outputs:
      vpc_id: .id

Get Involved​

Try binding a store hook to after.terraform.output against infrastructure you didn't apply through Atmos. Tell us what's missing — an aggregate event for --affected/--all output runs, or another lifecycle command entirely. Open an issue or start a discussion at github.com/cloudposse/atmos.

The Problem​

Atmos stores support many backends. Examples are AWS SSM, AWS Secrets Manager, HashiCorp Vault, Azure Key Vault, GCP Secret Manager, Redis, Artifactory, 1Password, Keychain, and GitHub Actions. The !store and !store.get YAML functions can read any value from these stores. But Atmos gave you only two ways to write a value into a store. You could declare the value as a formal secret with atmos secret. Or you could use the one existing store hook. That hook only copies a Terraform output into a store after apply runs. Atmos had no supported way to write other values, such as a Docker image tag from a container build step, a build number, or a deployment marker created mid-workflow. To write one of these values, you had to use the AWS CLI, curl, or a custom shell script in the workflow.

The Fix​

Atmos now has a new CLI command group named atmos store. This command group gives you raw CRUD access to any configured store. Atmos also has a new workflow step named type: store. This step writes a value from a workflow, a custom command, or a hook. Neither the CLI nor the step requires you to declare a value first. Both work directly on any backend listed under stores: in atmos.yaml. You can scope a value to a stack and a component. Or you can omit the stack and component to make the value global.

atmos store set app-metadata image_tag sha256:abc123 --stack=prod --component=ecs-service
atmos store get app-metadata image_tag --stack=prod --component=ecs-service
atmos store list

The store step closes the loop with the existing read functions. First, a workflow builds an image and pushes it. Next, the workflow writes the resulting tag to a store. Later, a completely separate deploy run reads the tag back with !store or !store.get. This flow needs no shared Terraform state and no custom scripts.

steps:
  - name: push
    type: container
    action: push
    with:
      image: myapp:{{ .env.GIT_SHA }}

  - name: record-tag
    type: store
    action: write
    with:
      store: app-metadata
      key: image_tag
      value: "{{ .steps.push.metadata.digest }}"
      stack: prod
      component: ecs-service

The store step is a normal registered step type. Because of this, it also runs as a hook through the existing kind: step bridge. You need no extra configuration to run it after terraform apply.

Atmos allows you to write to a secret: true store on purpose. For example, a step can generate a password and write it straight to a secret backend. Both the CLI and the step support this case. But this write is only a shortcut. It is not a replacement for atmos secret. It skips declaration and scope tracking. When a value must be tracked as a formal secret, use secrets.vars and atmos secret set instead.

How to Use It​

Set and read a value scoped to a stack and a component:

atmos store set app-metadata image_tag sha256:abc123 --stack=prod --component=ecs-service
atmos store get app-metadata image_tag --stack=prod --component=ecs-service --format=json

Delete the value. Then list the configured stores:

atmos store delete app-metadata image_tag --stack=prod --component=ecs-service
atmos store list

Write a value from a workflow step. Then read the value back in stack configuration for a completely different component:

# workflow
- name: record-tag
  type: store
  action: write
  with:
    store: app-metadata
    key: image_tag
    value: "{{ .steps.push.metadata.digest }}"

# stacks/.../ecs-service.yaml
vars:
  image_tag: !store app-metadata prod ecs-service image_tag

Both the command group and the step type are experimental for now. We may change them as we get feedback from users.

Get Involved​

Try atmos store and the store step in your own build-to-deploy pipeline. Tell us what is missing. Examples are a matching read step, bulk import and export, or another feature. You can open an issue or start a discussion at github.com/cloudposse/atmos.

For an introduction to defining and selecting tags and labels, see the original feature announcement.

How to Use It​

Use tags and labels on their own:

atmos workflow deploy --tags networking --labels deployment:dev

--stack, --tags, and --labels are all optional selectors. Combine the ones that define the scope you need:

atmos workflow deploy \
  --stack tenant1-ue2-dev \
  --tags networking \
  --labels deployment:dev

Use the same selectors you already use with normal Atmos commands, while keeping the workflow's ordering, dependencies, parallel steps, and matrix steps intact.

Get Involved​

Try tags and labels with the workflows you already use for targeted deployments. If a workflow pattern needs a different selection model, open an issue with the command and component scope you want to express.

The Problem​

A CI job that needs a tool's configured version — to pass to another action, or write to GITHUB_OUTPUT — had to reach for something like:

version=$(atmos toolchain get vale-cli/vale 2>&1 | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
echo "version=$version" >> "$GITHUB_OUTPUT"

That's a lot of shell just to answer "what version is configured?" — a regex to strip a checkmark and color codes, head -1 because the human-readable view can list more than one line, and 2>&1 because the output goes to stderr, not stdout.

The Fix​

atmos toolchain get now supports a --format flag with two script-friendly output modes alongside the existing human-readable table: plain prints just the bare version string, and json prints structured output including whether that version is installed.

How to Use It​

Grab a version with nothing to parse:

$ atmos toolchain get vale-cli/vale --format=plain
2.20.0

Which collapses the CI snippet above to:

version=$(atmos toolchain get vale-cli/vale --format=plain)
echo "version=$version" >> "$GITHUB_OUTPUT"

Ask for more than the version string with --format=json:

$ atmos toolchain get terraform --format=json

{
  "tool": "hashicorp/terraform",
  "version": "1.9.8",
  "installed": false
}

--format=plain only makes sense for a single resolved version, so it's rejected when combined with --all (which lists every available version) — use --format=json there instead, which returns the full list with each entry's installed and default status.

Get Involved​

Try --format=plain or --format=json the next time you're piping a tool version into a script. If you run into a toolchain command that still only prints decorated, hard-to-parse output, please open an issue so we can add the same script-friendly modes there too.

The Problem​

Atmos has always known the dependency graph — dependencies.components declares what each component needs, and bulk operations like atmos terraform apply --all already execute in topological order. But the selection never followed the edges. Selecting a stack with -s dev, or a set of components with --tags or --labels, ran only what matched; prerequisites living in another stack (or without the matching tag) were silently out of scope. Deploying "dev and everything dev needs" meant knowing the prerequisite chain yourself and scripting around Atmos — exactly the kind of glue the tool exists to remove.

The reverse direction had the same gap: after changing a shared component, running everything that depends on it was only possible through --affected, not from an arbitrary selection.

The Fix​

Every multi-component terraform selection — --all, --components, --query, -s, --tags, --labels, and --affected — now accepts two closure flags:

• The --include-dependencies[=N] flag expands the selection with everything it depends on (its prerequisites), N levels deep. The bare flag means unlimited depth.
• The --include-dependents[=N] flag expands in the reverse direction: everything that depends on the selection.

Selectors choose the seed; the closure flags expand it. Expanded components execute even when they don't match the selectors — a prerequisite doesn't need your env=dev label to be required by something that has it. Execution stays in dependency order (reverse order for destroy), and cross-stack edges are followed: apply --all -s dev --include-dependencies will run a prerequisite in core before the components in dev.

The same flags work on atmos list components, atmos list stacks, and atmos list instances, so you can see the exact set a bulk run would execute before running it.

Scoping stays lazy: Atmos first walks a lightweight structural graph to find the closure, then fully evaluates (templates, YAML functions, authentication) only the stacks the closure actually touches. An unrelated account's unreachable backend still can't break your deploy.

How to Use It​

Apply everything labeled for dev, plus all of its prerequisites, in dependency order:

atmos terraform apply --all --labels=env=dev --include-dependencies

Bound the expansion to one dependency level:

atmos terraform plan --all --tags=app --include-dependencies=1

Tear down a component and everything that depends on it (dependents are destroyed first):

atmos terraform destroy --components=vpc -s dev --include-dependents

Preview the execution set without running anything:

atmos list components --labels=env=dev --include-dependencies
atmos list stacks --labels=env=dev --include-dependencies

A few things to know:

• Using --include-dependencies with destroy also destroys shared prerequisites of your selection — components other stacks may still rely on. Atmos warns when you combine them.
• Because metadata.tags and metadata.labels now drive scoping decisions before evaluation, they are selectors by design: plain strings, simple templates, and local functions like !env, !git.*, and !include are allowed, but values that require authentication or execution (!terraform.state, !store, !exec, atmos.Component, ...) are rejected with an error. This contract is enforced for every component whenever stacks are enumerated — by describe, list, and bulk terraform commands — even when no selector flag is used and the component is outside the current stack filter, so an existing impure value fails fast rather than surfacing later as a confusing scoping bug. The error names the offending component and stack manifest. Move those values into vars or settings instead — or, if you need time to migrate, set describe.settings.eager_evaluation: true in atmos.yaml to restore the previous full-evaluation behavior (see the describe configuration reference).
• If you already combine --affected --include-dependents with --tags or --labels, note the semantics changed: previously the tag/label filter also removed non-matching dependents from the expanded set; now selectors narrow only the seed and closure members are retained regardless. That is the whole point of closure expansion — but it does mean such runs can now include more components than before.
• The depth value must be attached with = (for example --include-dependencies=2). On the terraform commands a bare --include-dependencies followed by a separate value is also accepted, so take care that a following positional argument isn't consumed as the depth — Atmos rejects non-numeric values loudly rather than guessing.

Get Involved​

Try the closure flags on your own dependency graph and tell us where the semantics surprise you — especially around destroy ordering and depth bounds. Issues and discussions are open at github.com/cloudposse/atmos.

Stack manifests can now declare stack-wide metadata defaults that every component inherits, with the component's own metadata: still free to override them.

The Problem​

• Shared metadata meant duplicated metadata. If every component in a stack carries the same cost-center label or the same compliance tag, that block had to be copy-pasted into every component definition, and kept in sync by hand as components were added.
• A stack-level metadata: block looked like it should work, and didn't. Unlike vars/env/settings, a metadata: key at the root of a stack manifest was accepted but never applied — it silently did nothing, which is worse than a validation error.

The Fix​

A stack manifest can now declare a stack-wide metadata: default that's deep-merged into every component's own metadata:

metadata:
  labels:
    cost-center: platform

Only the fields that make sense as shared defaults are allowed here: labels, tags, custom, enabled, locked, and terraform_workspace_pattern. Component-identity fields — component, inherits, type, name, terraform_workspace — stay component-only, and setting one of these at the stack level is now a clear validation error instead of a silent no-op.

Precedence runs lowest to highest: stack-wide default → the component's metadata.inherits base-component chain → the component's own local metadata: block, which always wins:

components:
  terraform:
    vpc:
      metadata:
        labels:
          cost-center: network-team # overrides the stack-wide default for this component

How to Use It​

Combine a stack-wide default with the !labels/!tags YAML functions (see Tags and Labels) to feed a shared label set into every component's Terraform variables without repeating it:

metadata:
  labels:
    Namespace: eg
    Environment: prod

components:
  terraform:
    vpc:
      vars:
        tags: !labels   # var.tags (map) <- stack-wide metadata.labels, unless this component overrides them

The same mechanism also covers enabled/locked/custom/terraform_workspace_pattern, for cases like decommissioning an entire legacy stack without editing every component individually:

metadata:
  enabled: false # decommission every component in this stack

Get Involved​

Stack-wide metadata covers the fields that behave like shared defaults today. If there's another metadata field you'd want to set once for a whole stack, open an issue with your use case.

Atmos now lets multiple top-level manifests represent one logical stack while keeping each manifest's components and parent scope independent.

The Problem​

Teams often organize shared catalog imports and component instances by who owns them. Before this change, splitting one logical environment across parent manifests meant commands treated those files as separate stacks, or required a single large manifest that mixed unrelated scope and ownership.

That made it difficult to divide ownership without also changing how teams named, discovered, and operated the stack.

The Fix​

Atmos recognizes parent manifests with the same stack identity as one logical stack for discovery and component selection. Each manifest still resolves its own imports, globals, and component configuration, so values from one parent do not leak into another.

Within that logical stack:

• Distinct components from every parent appear together in stack discovery.
• Equivalent duplicate components choose a stable, lexical canonical source.
• Conflicting duplicate components remain errors with the parent manifests identified in the diagnostic.
• Inheritance stays self-contained: a base must be defined inline or explicitly imported by the parent that uses it.

How to Use It​

Give the related parent manifests the same stack identity through name, name_template, or name_pattern. For example, two manifests can use the same template-derived environment and stage:

# stacks/catalog/shared.yaml
components:
  terraform:
    chatops-base:
      metadata:
        component: mock
      vars:
        notifications_enabled: true

# stacks/parents/01-network.yaml
vars:
  environment: dev
  stage: shared

components:
  terraform:
    dns-primary:
      metadata:
        component: mock

# stacks/parents/02-platform.yaml
import:
  - catalog/shared

vars:
  environment: dev
  stage: shared

components:
  terraform:
    chatops:
      metadata:
        component: mock
        inherits:
          - chatops-base

With a matching stack name configuration, atmos describe stacks reports one logical stack, while atmos describe component chatops -s dev-shared retains the platform parent's scope and resolves its base through the platform manifest's explicit catalog import. A component defined only by the network parent is discoverable in the logical stack, but is not an implicit inheritance dependency of the platform parent.

Get Involved​

Try splitting a large logical stack along your team's ownership boundaries. If you encounter an import, inheritance, or duplicate-resolution case that is not clear, please open an issue with a minimal stack example.

tfmigrate turns these state changes into migration files that you store under version control. Atmos runs these files for you — manually from the CLI, or automatically from Terraform lifecycle hooks — in the same component context as atmos terraform plan and apply.

atmos terraform migrate plan s3-bucket -s plat-ue2-dev
atmos terraform migrate apply s3-bucket -s plat-ue2-dev

What Changed​

The new atmos terraform migrate command family adds:

• atmos terraform migrate plan to preview a migration.
• atmos terraform migrate apply to apply a migration.
• atmos terraform migrate list to inspect per-component hook and history context.
• kind: tfmigrate hooks for running migrations from Terraform lifecycle events.
• Zero-config history storage that reuses the component's Terraform backend.

Before tfmigrate runs, Atmos performs the normal Terraform component setup. This includes auth identity resolution, source provisioning, workdir provisioning, generated backend and varfiles, Terraform init, and workspace selection.

Dynamic Hooks​

kind: tfmigrate hooks default to mode: dynamic, so automation follows the Terraform operation:

hooks:
  state-migration:
    events:
      - before.terraform.plan
      - before.terraform.apply
    kind: tfmigrate
    mode: dynamic

before.terraform.plan runs tfmigrate plan. before.terraform.apply and before.terraform.deploy run tfmigrate apply. Use static mode: plan or mode: apply when a hook must always run one action.

Hooks run through Atmos, so they use the same identity as the Terraform operation. If the Terraform command or component selects an Atmos auth identity, the migration gets that same authenticated environment.

Recovering From Skipped Releases​

Provider removals are where this bites hardest. When a component release drops a provider configuration, every workspace that skips the intermediate release gets stuck. The state still holds resources from the removed provider, and Terraform refuses to plan:

Error: Provider configuration not present

To work with random_pet.legacy (orphan) its original provider configuration
at provider["registry.opentofu.org/hashicorp/random"].legacy is required,
but it has been removed.

Until now, the only fix was manual, and per workspace: restore a temporary provider override, apply, then delete the override again. Ship a migration alongside the release instead. The hook prunes the stale state entries before Terraform loads provider configurations, so workspaces can jump straight to the newest release:

migration "state" "drop_legacy_provider_state" {
  actions = [
    "rm random_pet.legacy",
  ]
}

Note: state rm abandons the remote object. It does not destroy it. This is usually what you want for provider-cleanup migrations. If you need to destroy the object, destroy it before you upgrade, or temporarily restore the provider configuration.

History Mode​

For idempotent migrations in automation, use tfmigrate history mode:

atmos terraform migrate apply s3-bucket -s plat-ue2-dev

History mode needs no configuration by default. Atmos looks for a custom tfmigrate config in four places: the hook's config field, the --tfmigrate-config / ATMOS_TFMIGRATE_CONFIG flag or environment variable, the TFMIGRATE_CONFIG environment variable, and a .tfmigrate.hcl file in the component. If none of these exist, Atmos generates a config on the fly.

The generated config stores migration history in the component's own Terraform backend. For an S3 or GCS backend, Atmos reuses the same bucket as the state. It stores history under a key namespaced by stack, component, and workspace, and it inherits the region, role ARN, and endpoint. For a local backend, Atmos stores the history file beside the state file.

Atmos records every applied migration and never reruns it. You don't need to set anything up.

To take control, provide your own config. Drop a .tfmigrate.hcl file in the component, set the hook's config field, or pass --tfmigrate-config / ATMOS_TFMIGRATE_CONFIG. Atmos exports stack, component, and workspace-scoped history variables, and copies the supported Terraform backend settings. Your custom config can then reuse the same bucket and identity setup:

tfmigrate {
  migration_dir = "./tfmigrate"

  history {
    storage "s3" {
      bucket   = env.ATMOS_TFMIGRATE_HISTORY_BUCKET
      key      = env.ATMOS_TFMIGRATE_HISTORY_KEY
      region   = env.ATMOS_TFMIGRATE_HISTORY_REGION
      role_arn = env.ATMOS_TFMIGRATE_HISTORY_ROLE_ARN
    }
  }
}

The default history key is:

tfmigrate/<stack>/<component>/<workspace>/history.json

That keeps multiple Atmos component instances from colliding when they share a Terraform backend bucket.

Important Limitation​

Single-file tfmigrate apply path.hcl is not idempotent by itself. A rerun can fail if a state address already moved or was removed. Prefer history mode instead. When the component's backend is S3 or GCS, the generated default gives you durable storage automatically. With a purely local backend, make sure the local history file survives between runs — for example, have your CI workflow persist it.

Learn More​

• atmos terraform migrate
• Hooks
• Terraform Component Configuration

The Problem​

The atmos vendor update command already finds and writes newer versions locally. Turning that into a reviewable pull request meant scripting Git branch/commit/push logic and a GitHub API client yourself, or reaching for an external action with its own permissions model, its own config format, and its own release cadence to track.

The Fix​

The --pull-request flag does the whole cycle natively: discover available updates, write them with the same format-preserving editor vendor update already uses, create or reuse a branch, commit, push, and open or update a pull request — through a provider-neutral Git registry (GitHub today; GitLab and Bitbucket can register without any command changes).

atmos vendor update --pull-request

Nothing happens unless there's actually an update: no updates means no branch, no commit, no push, no PR. Atmos fetches the base branch but never writes to it. It reuses an existing feature branch for the same scope and pushes it fast-forward only — repeated runs update the same PR instead of piling up duplicates.

How to Use It​

Scope updates to a named group instead of updating everything at once:

vendor:
  update:
    groups:
      platform:
        include: ["terraform/vpc", "terraform/eks/*"]
        exclude: ["terraform/eks/legacy"]
  ci:
    pull_request:
      branch_prefix: atmos/component-updater
      title: "chore(components): update {{ .scope.name }}"
      labels: [component-update]

atmos vendor update --group platform --pull-request

For a scheduled run, the official container image is all a workflow needs — no third-party action performs the update, commit, push, or PR creation:

on:
  schedule: [{ cron: "17 3 * * 1" }]
permissions:
  contents: write
  pull-requests: write
jobs:
  update:
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/cloudposse/atmos:${{ vars.ATMOS_VERSION }}
    steps:
      - uses: actions/checkout@v6
      - run: atmos vendor update --pull-request
        env: { GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} }

Set execution.mode: worktree when you'd rather the whole discover-branch-commit-push cycle ran in an isolated checkout instead of the workflow's own working tree — useful if other steps in the same job depend on an unmodified checkout while the update runs. In GitHub Actions, every run also appends a summary showing scope, counts, and the resulting PR link, independent of whether an update was found.

Triggering Downstream Workflows​

The example above uses the default GITHUB_TOKEN. This token is fine for opening the PR, but GitHub deliberately excludes its own default Actions token from re-triggering on: pull_request/ on: push workflows. As a result, a plan/validate workflow that's supposed to run against the new PR won't fire.

Pair the Component Updater with the github/sts auth integration to get a token that does trigger downstream Actions — a just-in-time GitHub App installation token, minted through Atmos Pro STS and exported as ATMOS_PRO_GITHUB_TOKEN. The --pull-request flag already prefers this token over GITHUB_TOKEN:

atmos auth exec --identity github-sts -- atmos vendor update --pull-request

No other flags or config changes are required. atmos auth exec mints and exports the token for the wrapped command's environment. The Component Updater's GitHub client picks it up automatically.

Get Involved​

Questions about scopes, groups, or CI publishing are welcome in the Atmos GitHub repository and the community Slack.

The Problem​

The atmos vendor pull command always re-fetches everything, every time, whether or not anything actually changed. That makes it slow to lean on as a drift check, so most teams just don't run it that way — they trust the checkout and find out otherwise the hard way. There was also no way to answer "does what's on disk still match what was vendored" without a network round trip, and no way to choose how loudly a stale checkout should complain before Atmos quietly re-fetches it.

The Fix​

Every atmos vendor pull now records a vendor.lock.yaml receipt for each vendored source: its declared origin, a resolved identity, and a checksum for every file it wrote. That receipt is what atmos vendor verify checks against, with zero network access:

atmos vendor verify

COMPONENT  PATH                              REASON
vpc        components/terraform/vpc/main.tf  checksum mismatch

It exits non-zero the moment anything doesn't match — a missing file or a modified one — so it drops straight into a CI gate. Add --component <name> to scope the check, or --format json for machine-readable output.

You also get to choose how a drifted checkout behaves on the next atmos vendor pull, instead of always silently re-fetching:

vendor:
  lock:
    enforcement: warn # silent | warn | strict

• The silent mode re-fetches with no reporting — the behavior every vendor pull had before this existed.
• The warn mode (the default) re-fetches and prints one line naming what drifted and why.
• The strict mode refuses to run at all until you pass --refresh-lock, so an unreviewed local edit can never get silently overwritten — or silently kept — without someone noticing.

How to Use It​

Gate CI on drift the same way you'd gate on any other check:

atmos vendor verify || exit 1

Override enforcement for a single invocation without touching atmos.yaml:

atmos vendor pull --lock-enforcement=strict

And when a source genuinely needs to move — not just recover from drift — version: can now be a semver range instead of only an exact pin:

sources:
  - component: vpc
    source: github.com/cloudposse/terraform-aws-vpc.git
    version: "^1.0.0"

The first atmos vendor pull resolves that range to a concrete tag and locks it there — every later pull reuses the locked version with no network call at all, until an explicit atmos vendor update or --refresh-lock re-resolves it. An exact pin like version: v1.5.0 behaves exactly as it always has: the manifest itself remains the single source of truth for what gets fetched.

Get Involved​

Questions about lock enforcement, vendor verify, or version ranges are welcome in the Atmos GitHub repository and the community Slack.

The native container build step can now provision that builder and cache directly, so a build's caching strategy lives next to the rest of its configuration instead of in separate Actions.

The Problem​

A docker buildx build that starts cold rebuilds every layer, even when nothing meaningful changed. Reusing a remote cache and a purpose-built builder solves this, but doing it by hand means composing several pieces: creating a builder with the right driver, pointing it at a registry-backed cache, and keeping all of that in sync with the rest of the build step.

The Fix​

action: build now accepts driver and cache:

- name: build
  type: container
  action: build
  provider: docker
  with:
    engine: buildx
    context: .
    dockerfile: Dockerfile
    tags:
      - registry.example.com/app:latest

    driver: docker-container   # shorthand — just the driver

    cache:
      from:
        - type: registry
          ref: registry.example.com/app:buildcache
      to:
        - type: registry
          ref: registry.example.com/app:buildcache
          mode: max

Atmos creates the named builder if it doesn't already exist and reuses it on later runs, so the builder's own cache persists across builds on the same host instead of starting cold every time. driver also accepts a full form when you need driver-specific options, such as pointing Buildx at a mirrored BuildKit image to avoid Docker Hub rate limits:

with:
  driver:
    name: atmos
    provider: docker-container
    opts:
      image: mirror.gcr.io/moby/buildkit:buildx-stable-1

How to Use It​

Add driver and cache under an existing action: build step wherever you use engine: buildx. If you build with bake instead, keep cache-from/cache-to in the bake file itself — Bake already supports them natively — and use driver for builder selection either way.

See the container step documentation for the full field reference, including the three ways to avoid Docker Hub rate limits.

Get Involved​

Try driver and cache in a build step and share feedback through GitHub issues.

Atmos can now validate the files affected by a change, so pull requests get actionable feedback without rechecking unrelated project inputs.

The Problem​

Configuration schema checks, stack validation, formatting rules, and workflow linting protect different parts of a project. Running every check over an entire repository can obscure the result that matters to the change under review.

The Fix​

Add --affected to the project-wide validator or to an individual validator. Atmos compares the current worktree with the Git merge-base, including local uncommitted and untracked files. In GitHub Actions, it reads the pull request base SHA automatically.

atmos validate --affected --format rich
atmos validate config --affected --base origin/main
atmos config validate --affected --base origin/main
atmos validate stacks --affected --base origin/main
atmos stack validate --affected --base origin/main
atmos validate editorconfig --affected --base origin/main
atmos validate ci --affected --base origin/main

Schema and EditorConfig checks validate changed inputs directly. Changes to a schema or rule configuration expand validation to the relevant full set. Stack validation runs whenever stack or Atmos configuration inputs change, preserving import and duplicate-component checks. Workflow validation sends only changed workflows to actionlint unless its configuration changes.

How to Use It​

Use the new Validation (affected) GitHub Actions job as a model for a project workflow. Check out enough Git history for the merge-base, then run the command with rich output:

- uses: actions/checkout@v6
  with:
    fetch-depth: 0
- run: atmos validate --affected --format rich

Get Involved​

Try affected validation in your pull request workflow and share feedback through GitHub issues.