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.

The atmos init command initializes an Atmos project from a template chosen for the job at hand: a minimal cloud-agnostic project, an AWS application SDLC project, or a cloud landing zone. Each template creates the configuration, structure, and operational path appropriate to that project rather than asking every team to assemble it from scratch.

View the full init example

Initialize the Project You Need​

The basic template gives a new project a small, cloud-agnostic foundation with a real greeting Terraform component. It creates a local file, so a developer can validate and deploy the generated project without a cloud account, credentials, or an emulator. The point is to prove that the initialized project works before anyone starts extending it.

For teams beginning an application project, the aws/app catalog template establishes a complete AWS application SDLC repository with dev, staging, and production stacks, native CI, and an emulator-proven application component. For a platform foundation, aws/landing-zone initializes dev, staging, and production environments with a conventional AWS baseline for audit, KMS, SSM, monitoring, and IAM. The catalog also includes GCP and Azure landing-zone starting points.

A Consistent Initialization Contract​

An interactive invocation lets a developer choose the project template and answer only the questions that shape it. Required answers, patterns, option lists, and boolean values are enforced consistently whether they come from prompts, defaults, persisted values, or --set. The same initialization can therefore be repeated from automation without bypassing the template’s contract.

Built-in templates travel with the Atmos binary. Catalog templates resolve to the source associated with that build, so a team initializes from a known template version rather than an accidental snapshot of a repository.

Build Your Organization's Golden Paths​

The init catalog distributes proven starting points with Atmos. For organization-owned golden paths that your platform team distributes through a catalog or Git repository, see the scaffolds announcement.

See the Init Command Documentation for the full template list.

The Problem​

An SBOM that quietly excludes a dependency category can create more risk than no SBOM at all. The person deciding whether an artifact is ready for compliance review needs to see gaps like these:

• A provider version without its checksum
• A module selected from a mutable ref
• An unavailable module graph

Terraform's provider lock file, vendored source receipts, and OCI artifact digests already contain much of the evidence that infrastructure teams need. Until now, that evidence lived in separate places, and no tool could render it as a single standards-based document.

The Fix​

Generate a provenance/build-input SBOM for Terraform-managed infrastructure:

atmos sbom generate --format cyclonedx-json --output infra.sbom.json

The first release inventories four evidence domains:

• Atmos-managed sources recorded in vendor.lock.yaml, including vendor.yaml, component.yaml, and mixins
• OCI source artifacts pinned by their selected manifest digest
• Terraform providers from .terraform.lock.hcl, including recorded archive checksums
• Terraform modules from terraform modules -json, resolved to a commit, OCI digest, or content hash when possible

The command emits CycloneDX JSON or SPDX JSON from the same graph. The two documents describe the same components and relationships.

Compliance Without False Confidence​

An SBOM is only useful when its coverage is clear. The default provenance mode includes coverage diagnostics for each adapter and emits the evidence that is available. It deliberately does not claim that the document represents every dependency or deployed workload in the environment.

For a Terraform-scoped NTIA-baseline check, use --mode ntia and identify the subject:

atmos sbom generate \
  --mode ntia \
  --subject-name infra-live \
  --subject-version "$(git rev-parse --short HEAD)" \
  --subject-supplier "Example, Inc." \
  --format spdx-json \
  --output infra-live.spdx.json

NTIA mode fails when required provenance is incomplete, such as:

• Missing subject information
• A provider lock without a SHA-256 archive checksum
• A module without immutable resolution evidence
• An unavailable module-graph interface

A failed compliance-mode invocation is more useful than a document that silently leaves evidence out.

How to Use It​

Start with the default provenance mode to inspect the evidence and coverage for initialized Terraform components:

atmos sbom generate --format cyclonedx-json --output infra.sbom.json

Add --include-files when the exact vendor.lock.yaml file inventory belongs in the document:

atmos sbom generate --include-files --output infra.sbom.json

The command uses the Terraform executable configured by components.terraform.command in each component directory. If it is unset, Atmos uses terraform. Module inventory currently requires Terraform 1.10 or later because it relies on the stable terraform modules -json interface.

If your project configures tofu, Atmos honors that choice. Atmos does not parse Terraform's internal module-installation files as a fallback. Until OpenTofu exposes an equivalent stable structured interface, Atmos marks module coverage unavailable, and NTIA mode refuses the scope.

What's Next​

This is the foundation for broader dependency coverage — it's not yet feature complete. The next adapters extend coverage across the other component types Atmos already supports:

• Helm and Helmfile locks
• Kubernetes manifests
• Typed deployed-container image discovery
• OCI SBOM attestations or scanner integration for image contents
• OpenTofu module graphs

The shared graph and coverage contract mean those additions extend both CycloneDX and SPDX consistently.

Read the full SBOM command reference and the provenance design.

Get Involved​

The initial release is experimental. Questions about the evidence model, new adapters, or compliance workflows are welcome in the Atmos GitHub repository and the community Slack.

Atmos scaffolds turn a golden path into an executable contract. Use a local template, register one in atmos.yaml, or point to a Git repository—including a GitHub template repository—and let the same template guide developers, automate CI, and evolve with the platform.

Creation is only day one. Golden paths accumulate improvements after projects have adopted them: updated CI conventions, guardrails, shared configuration, and boilerplate. Atmos scaffolds include an optimistic three-way merge process so a project can take those upstream improvements without blindly replacing the custom work that happened after initialization.

View the full scaffolding example

From Repository Copy to Golden Path​

The usual alternative is either a generic template that every team must customize by hand or a matrix of near-duplicate templates for every language, environment, compliance rule, and deployment option. The first creates drift. The second makes the platform team responsible for maintaining an ever-growing catalog of almost-the-same repositories.

A scaffold keeps one template and makes it adapt to the project being created. The platform team owns the contract; the consuming team supplies only the choices that belong to its project.

What the Contract Enforces​

• Validated inputs. Required fields, patterns, select and multiselect options, and boolean values are validated for interactive answers, defaults, presets, persisted values, and --set flags. Platform policy does not disappear when a template runs in CI.
• Conditional prompts and files. A field or file can use when: and the answers collected so far. A template can ask for a vendored component version only when vendoring is enabled, then generate the corresponding manifest only in that case.
• Lifecycle hooks. Templates can run declared work before or after generation—formatting, validation, or setup—with the same condition engine used by Atmos workflows and CI hooks. Teams can use --skip-hooks as an explicit per-invocation escape hatch.
• Day-two updates. The atmos scaffold generate --update command re-runs a template against an existing project and performs an optimistic three-way merge. It is a strong fit for shared boilerplate that changes infrequently across many projects: non-overlapping improvements can be carried forward, while real conflicts stay visible instead of silently overwriting local work. The --merge-strategy option selects manual, ours, or theirs conflict handling.

Both when: forms use the condition language shared by Atmos workflows and CI hooks. The answers variable exposes the values collected so far, allowing a golden path to express its decisions once rather than encode them in a pile of repository variants.

Keep GitHub Templates, Add a Platform Contract​

GitHub template repositories remain a useful ownership and discovery mechanism. Atmos adds the behavior they intentionally do not provide: typed choices, conditional generation, hooks, and a safe path for bringing template improvements back to an existing project. A remote source can be pinned to a branch, tag, or commit with --ref, so platform teams can make a deliberate release available instead of distributing an accidental snapshot.

See the Scaffold Command Documentation for the field, hook, remote-source, and update reference.

Proxies also make subcommands first-class executable names. A command-named link points back to Atmos; when it is invoked, Atmos reads the executed name, finds its proxy configuration, and runs the configured tool with its prefix arguments and the caller’s arguments. A multicall tool such as uutils/coreutils can therefore expose coreutils ls as the normal ls command—without shell aliases, copied shims, or a different invocation in every repository.

Install on Demand, Keep Versions Pinned​

An alias resolves the package name, and a proxy maps the familiar command to the package and any prefix arguments it needs:

toolchain:
  aliases:
    coreutils: uutils/coreutils
  proxies:
    ls:
      tool: coreutils
      args: [ls]

coreutils 0.9.0

Get Started​

Activate every configured proxy in the current Bash or Zsh session with one command:

eval "$(atmos toolchain env)"

The normal ls command now invokes the ls proxy, which resolves to the pinned coreutils ls implementation. On its first invocation, the proxy installs that version if it is not already available, then runs it with the supplied arguments. Later invocations reuse the installed binary.

For an intentionally eager setup—for example, a CI image or an offline preparation step—install every pinned tool in .tool-versions before activating the environment:

atmos toolchain install
eval "$(atmos toolchain env)"

Promote a Subcommand to a Command​

The same on-demand mechanism is useful when a package exposes many operations through one binary. The args list supplies the subcommand or default flags, while the proxy name becomes the command that developers and automation invoke. This turns a useful part of a larger tool into a normal, version-pinned command without a wrapper script.

Useful Beyond an Interactive Shell​

Atmos prepares the proxy environment for built-in command runners, workflows, hooks, components, and custom commands. A project can therefore use the familiar command name in its automation while retaining the tool version and source in version control. Developers can opt into the same proxy directory in their terminal without modifying the system command globally.

The boundary is deliberate: a proxy is available only to Atmos child processes or to a shell that has explicitly activated the toolchain environment. It never replaces the system ls command for the rest of the machine.

Portable by Design​

Atmos creates symbolic links on Unix-like systems and executable hard links on Windows, avoiding a Windows symlink-privilege requirement. Proxy activation also carries the configuration context across directory changes, so the selected toolchain remains associated with the project that declared it.

See Toolchain Proxies for the configuration reference, platform details, and troubleshooting guidance.

What's New​

The !terraform.state YAML function now supports Azure Blob Storage (azurerm) backends, joining existing support for S3 and local backends. This means you can retrieve Terraform outputs from Azure-backed state files at lightning speed—without the overhead of Terraform initialization.

Why This Matters​

Before this feature, if you were using Azure Blob Storage as your Terraform backend, you had two options for reading remote state:

1. !terraform.output - Slow but reliable. Requires full Terraform initialization, provider downloads, and varfile generation.
2. !store - Fast but requires extra setup. You had to manually configure external secret stores.

Now you can use !terraform.state with Azure backends—getting 10-100x faster performance compared to !terraform.output by reading directly from blob storage.

How It Works​

Backend Configuration​

Configure your Terraform component with an azurerm backend:

components:
  terraform:
    vpc:
      backend_type: azurerm
      backend:
        azurerm:
          storage_account_name: "mystorageaccount"
          container_name: "tfstate"
          key: "vpc.terraform.tfstate"

Reading State​

Use the !terraform.state function to read outputs:

components:
  terraform:
    eks-cluster:
      vars:
        # Get vpc_id output from vpc component in current stack
        vpc_id: !terraform.state vpc vpc_id

        # Get private subnet IDs
        subnet_ids: !terraform.state vpc private_subnet_ids

        # Get first subnet using YQ expression
        subnet_id: !terraform.state vpc .private_subnet_ids[0]

Cross-Stack References​

Reference components from different stacks:

components:
  terraform:
    tgw:
      vars:
        # Get VPC ID from production stack
        vpc_id: !terraform.state vpc plat-ue2-prod vpc_id

        # Use template for dynamic stack names
        vpc_id: !terraform.state vpc {{ printf "net-%s-%s" .vars.environment .vars.stage }} vpc_id

Authentication​

The Azure Blob Storage integration uses Azure DefaultAzureCredential, which supports multiple authentication methods automatically:

1. Environment variables - AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET
2. Managed Identity - When running in Azure (AKS, VMs, Functions)
3. Azure CLI credentials - az login
4. Visual Studio Code credentials - Authenticated VS Code sessions

No additional configuration needed—just authenticate using your preferred method.

Workspace Handling​

Azure Blob Storage uses a specific naming convention for workspaces:

• Default workspace: Uses the key as-is (e.g., terraform.tfstate)
• Non-default workspaces: Appends workspace as suffix (e.g., terraform.tfstateenv:dev)

Atmos handles this automatically—you don't need to worry about the naming convention.

Example​

If you have:

• Key: apimanagement.terraform.tfstate
• Workspace: dev-wus3-apimanagement-be

Atmos will look for: apimanagement.terraform.tfstateenv:dev-wus3-apimanagement-be

Performance Benefits​

Before: Using !terraform.output​

$ time atmos terraform plan eks-cluster -s plat-ue2-dev

# Must initialize Terraform for each dependency
Initializing vpc component...
Downloading providers...
Generating backend config...
Generating varfiles...
Reading outputs...

real    2m34.521s

After: Using !terraform.state​

$ time atmos terraform plan eks-cluster -s plat-ue2-dev

# Direct blob storage access
Reading state from Azure Blob Storage...

real    0m3.142s

~50x faster in this example—and the speedup grows with infrastructure complexity.

Advanced Features​

YQ Expressions​

Use YQ expressions for complex data extraction:

vars:
  # Get nested map values
  db_endpoint: !terraform.state database .config_map.endpoint

  # String concatenation
  jdbc_url: !terraform.state 'postgres .master_hostname | "jdbc:postgresql://" + . + ":5432/events"'

  # Default values for unprovisioned components
  username: !terraform.state config .username // "default-user"

Caching​

Results are cached in memory per CLI execution:

vars:
  # All three calls use the same cached result
  sg_id_1: !terraform.state vpc security_group_id
  sg_id_2: !terraform.state vpc security_group_id
  sg_id_3: !terraform.state vpc {{ .stack }} security_group_id

The first call reads from Azure; subsequent calls return cached data instantly.

Error Handling​

• Blob not found (404): Returns null (component not provisioned yet)
• Permission denied (403): Returns clear error message
• Network errors: Automatically retries up to 2 times with exponential backoff

Technical Details​

Implementation Highlights​

• Azure SDK for Go - Uses official github.com/Azure/azure-sdk-for-go/sdk/storage/azblob package
• Client caching - Azure Blob clients are cached per storage account/container
• Retry logic - Automatic retry with exponential backoff for transient failures
• Nil safety - Robust error handling prevents panics
• Test coverage - Comprehensive unit tests with mocked Azure SDK
• Cross-platform - Works on Linux, macOS, and Windows

Backend Configuration Options​

All standard Azure backend options are supported:

backend:
  azurerm:
    storage_account_name: "mystorageaccount"  # Required
    container_name: "tfstate"                  # Required
    key: "terraform.tfstate"                   # Optional (default: terraform.tfstate)
    # Authentication happens via DefaultAzureCredential

Migration Guide​

From !terraform.output to !terraform.state​

The syntax is identical—just replace !terraform.output with !terraform.state:

# Before
vpc_id: !terraform.output vpc vpc_id

# After
vpc_id: !terraform.state vpc vpc_id

From !store to !terraform.state​

Simplify your configuration by removing store setup:

# Before: Required store configuration
vpc_id: !store azurekeyvault plat-ue2-dev vpc vpc_id

# After: Direct state access
vpc_id: !terraform.state vpc vpc_id

Examples​

Basic Usage​

components:
  terraform:
    app:
      vars:
        # String output
        security_group_id: !terraform.state security-group id

        # List output
        subnet_ids: !terraform.state vpc private_subnet_ids

        # Map output
        config: !terraform.state config config_map

Cross-Region References​

components:
  terraform:
    replication:
      vars:
        # Reference component from different region
        primary_db: !terraform.state database {{ printf "%s-use1-%s" .vars.tenant .vars.stage }} endpoint

Disaster Recovery Scenarios​

components:
  terraform:
    failover:
      vars:
        # Primary region
        primary_vpc: !terraform.state vpc plat-ue2-prod vpc_id

        # DR region with default fallback
        dr_vpc: !terraform.state vpc plat-uw2-prod .vpc_id // "vpc-mock-dr"

Considerations​

• Secrets exposure: Using !terraform.state with secrets will expose them in atmos describe output
• Permission scoping: Ensure your Azure credentials have access to all referenced storage accounts
• Cross-region access: Consider latency when reading state across regions
• Cold starts: Components not yet provisioned return null (use YQ default values to handle this)

Try It Now​

Upgrade to the latest Atmos release and start using Azure Blob Storage backends:

# Check your version
atmos version

# Describe a component using Azure backend
atmos describe component vpc -s plat-ue2-dev

# Use !terraform.state in your stack configs
# (See examples above)

Documentation​

• !terraform.state Function Reference - Complete usage documentation
• Terraform Backends - Backend configuration guide
• Remote State - Data sharing patterns

Get Involved​

We're building Atmos in the open and welcome your feedback:

• 💬 Discuss - Share thoughts in GitHub Discussions.
• 🐛 Report Issues - Found a bug? Open an issue.
• 🚀 Contribute - Want to add features? Review our contribution guide.

Next up: Google Cloud Storage (GCS) backend support for !terraform.state. Stay tuned!

Atmos now includes GitHub Actions workflow validation as an experimental native-CI command. Run it from your workstation or in the workflow that it checks:

atmos ci validate

# Equivalent validation-oriented alias
atmos validate ci

Validate Before the Push​

With no arguments, atmos ci validate recursively checks every .yml and .yaml file in the current working directory's .github/workflows. It uses the built-in actionlint integration, so the linting capability ships with Atmos rather than requiring a separately installed binary.

A successful run gives a compact confirmation:

✓ Validated 3 GitHub Actions workflow file(s) in .github/workflows.

Findings include the workflow path, line, column, and actionlint rule. They fail the command, which makes validation suitable for both a pre-push check and a CI gate.

Check a Fixture or Another Directory​

Sometimes the workflows you want to validate do not live in the current directory's default location — for example, when testing generated workflows or fixtures. Use --workflow-path to point at that directory. Atmos recursively finds workflow YAML beneath it:

atmos ci validate --workflow-path tests/fixtures/scenarios/invalid-github-actions-workflows/.github/workflows

That repository fixture intentionally uses branch instead of branches in a push trigger. The command reports the line and exits with status 1, making it a quick end-to-end smoke test of the feature. You can also select specific files directly:

atmos ci validate .github/workflows/plan.yml .github/workflows/apply.yml

--workflow-path and explicit workflow-file arguments are intentionally separate selectors and cannot be combined. This keeps the validation scope unambiguous.

Put It in GitHub Actions​

Add a validation step after checkout:

name: Validate workflows

on:
  pull_request:

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: cloudposse/github-action-setup-atmos@v2
      - run: atmos ci validate

When native CI is enabled, Atmos turns findings into line-anchored GitHub Actions annotations:

ci:
  enabled: true

Annotations are enabled by default once ci.enabled is true; set ci.annotations.enabled: false to suppress them. Outside GitHub Actions, the same command has no provider side effects and simply renders its diagnostics.

SARIF Is Explicit​

For a separate Code Scanning upload or an artifact, request SARIF explicitly:

atmos ci validate --format=sarif > actionlint.sarif

Atmos does not upload SARIF automatically. That avoids duplicate pull-request feedback and keeps security-events: write unnecessary unless your workflow deliberately adds a SARIF upload step.

The validator respects .github/actionlint.yaml and .github/actionlint.yml. Its optional ShellCheck and Pyflakes integrations are disabled for now, so the command stays deterministic and does not depend on tools installed on the runner.

Learn More​

• atmos ci validate — usage, flags, and output formats
• Native CI — native CI behavior and configuration
• CI configuration — enable annotations and other CI features