Atmos CI

Atmos CI

Purpose

Use this skill for CI/CD workflows that run Atmos in GitHub Actions, Atlantis, or other automation systems. Prefer Atmos Native CI: run the Atmos CLI directly in CI, with stack config as the source of truth and atmos describe affected/atmos list instances producing matrices.

Do not recommend the deprecated cloudposse/github-action-atmos* wrapper actions or cloudposse/github-action-setup-atmos. Replace those with containerized Native CI jobs that run Atmos commands directly.

Related Skills

Native CI First

Configure Atmos CI features in atmos.yaml; workflow YAML alone is not enough when users want summaries, outputs, checks, comments, or planfile behavior:

ci:
  enabled: true
  output:
    enabled: true
    variables:
      - has_changes
      - has_errors
      - exit_code
      - resources_to_create
      - resources_to_change
      - resources_to_replace
      - resources_to_destroy
      - stack
      - component
      - summary
  summary:
    enabled: true
  checks:
    enabled: true
    context_prefix: atmos
    statuses:
      component: true
      add: true
      change: true
      destroy: true
  comments:
    enabled: true
    behavior: upsert

ci.output.variables is an allowlist filter over the variables the terraform CI plugin already builds (an empty list means write all of them); it never invents new names. Only the terraform plugin implements native output variables today (helm/helmfile/kubernetes plugins do not). Beyond has_changes/has_errors/exit_code/stack/component/command/summary, plan/apply/destroy add resources_to_create/resources_to_change/resources_to_replace/resources_to_destroy, apply/test add success, and test adds tests_total/tests_passed/tests_failed/ tests_errored/tests_skipped. After a successful apply, each Terraform output is also written as output_<name> — those bypass the allowlist and are always included.

Log Groups

Configure ci.groups.mode to fold Atmos output into collapsible GitHub Actions ::group:: regions and cut log noise:

ci:
  enabled: true
  groups:
    mode: auto      # auto (default) | invocation | off

• auto (default): the finest grouping that applies to each command — one group per workflow/custom-command step, and one group per phase (terraform init, terraform apply, etc.) of a terraform/tofu invocation.
• invocation: one group around the whole top-level atmos <command> run; suppresses finer step/phase grouping.
• off: no grouping.

Modes are mutually exclusive because CI providers do not support nested groups; do not try to combine step-level and invocation-level grouping.

Use the Atmos toolchain for Terraform/OpenTofu and related tools so CI does not depend on runner images or external setup actions:

toolchain:
  aliases:
    terraform: hashicorp/terraform
    opentofu: opentofu/opentofu
    tofu: opentofu/opentofu

terraform:
  dependencies:
    tools:
      terraform: "1.10.3"
      # For OpenTofu projects:
      # opentofu: "1.10.3"

Discourage hashicorp/setup-terraform, opentofu/setup-opentofu, and similar setup actions in Atmos CI examples. Prefer dependencies.tools when the tool is required by a stack, component, workflow, or custom command; Atmos installs and injects the exact version for that execution context.

Use explicit atmos toolchain install ... steps only for job-level scripts that need tools not declared as component, workflow, or custom command dependencies. In GitHub Actions, run atmos toolchain env --format=github; Atmos appends toolchain paths to $GITHUB_PATH when that file is available, so later steps can call those tools directly. If a CI fix adds atmos toolchain install <tool> for a tool used by an Atmos command, workflow, hook, or component, convert that tool into the owning dependencies.tools declaration instead.

Primary GitHub Actions pattern:

jobs:
  plan:
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/cloudposse/atmos:${{ vars.ATMOS_VERSION }}
    permissions:
      contents: read
      id-token: write
      statuses: write
      pull-requests: write
    env:
      ATMOS_PROFILE: github
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    steps:
      - uses: actions/checkout@v6
      - run: atmos terraform plan vpc -s prod

For new workflows, use the container image and direct Atmos commands.

SBOM Workflow Artifacts

Use atmos sbom generate --upload to retain the generated CycloneDX or SPDX document with a native CI run. This is an optional provider capability: it must not be modeled as a status check, PR comment, or dependency-graph submission.

GitHub Actions does not expose its artifact-runtime credentials to ordinary run: steps. Surface them with the Atmos github-runtime action, then run the command. The generated file is still written to --output (or stdout); --upload additionally stores the same bytes as a workflow artifact.

permissions:
  contents: read

steps:
  - uses: actions/checkout@v6
  - uses: cloudposse/atmos/actions/github-runtime@v1
    with:
      mode: env
  - run: atmos sbom generate --format spdx-json --output sbom.spdx.json --upload
    env:
      GITHUB_TOKEN: ${{ github.token }}

GitHub's SBOM APIs export or request GitHub-generated SPDX reports; they do not accept an arbitrary Atmos SBOM. Say "workflow artifact" or "CI publication," never "Dependency Graph upload." See atmos-sbom for evidence and coverage semantics.

Matrix Patterns

Use affected matrices for pull requests and targeted deploys. When ci.enabled: true and ci.output.enabled: true are configured, Atmos writes native outputs to $GITHUB_OUTPUT; pass them between steps and jobs with step id, job outputs, and needs.<job>.outputs.*.

jobs:
  affected:
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/cloudposse/atmos:${{ vars.ATMOS_VERSION }}
    outputs:
      matrix: ${{ steps.affected.outputs.matrix }}
      count: ${{ steps.affected.outputs.count }}
    steps:
      - uses: actions/checkout@v6
      - id: affected
        run: atmos describe affected --format=matrix

  deploy:
    needs: affected
    if: ${{ needs.affected.outputs.count != '0' }}
    strategy:
      fail-fast: false
      matrix: ${{ fromJson(needs.affected.outputs.matrix) }}
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/cloudposse/atmos:${{ vars.ATMOS_VERSION }}
    env:
      ATMOS_PROFILE: github
    steps:
      - uses: actions/checkout@v6
      - run: atmos terraform deploy "${{ matrix.component }}" -s "${{ matrix.stack }}"

Use all-instance matrices for full estate bootstraps, release deploys, or Atmos Pro inventory/drift workflows:

- id: instances
  run: atmos list instances --format=matrix

Keeping privileged components out of CI

Native CI ignores the legacy settings.github.actions_enabled setting. To keep privileged components (such as aws-teams, iam, tfstate-backend) out of automated plan/apply, label components and filter the matrix. Labels match positively only (no negation), so set a default and override it:

# stacks/orgs/acme/_defaults.yaml - default for every component
metadata:
  labels:
    ci: auto

# stacks/catalog/iam.yaml - privileged instances override it
components:
  terraform:
    iam:
      metadata:
        labels:
          ci: manual

atmos describe affected --format=matrix --labels=ci=auto
atmos terraform plan --affected --labels=ci=auto
# Dependents of changed components as their own matrix entries.
atmos describe affected --format=matrix --include-dependents --flatten --labels=ci=auto

• --tags matches ANY tag in metadata.tags; --labels matches ALL key=value/key:value pairs in metadata.labels. Env vars: ATMOS_TAGS, ATMOS_LABELS. Matching is case-sensitive, duplicate label keys are last-wins, and a component without metadata (or without tags/labels) never matches.

• Both filter every output format, including --format=matrix. On the command line they are rejected with --upload (the Atmos Pro inventory upload is always unfiltered); a selector that only comes from a job-level ATMOS_TAGS/ATMOS_LABELS is ignored with a warning instead.

• atmos terraform --affected|--all --include-dependents --tags|--labels selects the same components as describe affected: non-matching dependents are skipped and their matching dependents still run in order. Prerequisites from --include-dependencies are not filtered.

• With --include-dependents, a non-matching affected component is removed and its matching dependents become top-level entries with affected: dependent. --flatten (env ATMOS_DESCRIBE_AFFECTED_FLATTEN; requires --include-dependents; not with --upload) lifts every remaining dependent into the top-level list, which is how a matrix includes dependents.

• A job-level ATMOS_TAGS/ATMOS_LABELS applies to every describe affected and multi-component atmos terraform step in the job. Set them per step when a job mixes those commands.

• An empty matrix is {"include":[]}, never an empty string. Guard downstream jobs with the count output (needs.affected.outputs.count != '0'), not matrix != ''.

• Run privileged components from a separate workflow and role that selects --labels=ci=manual.

• Backstop: an OPA policy in settings.validation (rule head errors[message] in package atmos) that checks input.process_env.GITHUB_ACTIONS == "true" and input.metadata.labels.ci == "manual". The policy fails the job rather than skipping it; the matrix selector is what keeps the job from starting. schema_path is resolved relative to schemas.opa.base_path, which must be set in atmos.yaml (otherwise: the file '...' does not exist for schema type 'opa'):

  schemas:
    opa:
      base_path: "stacks/schemas/opa"

• An empty --labels=/--tags= (or empty ATMOS_LABELS/ATMOS_TAGS) applies no filter and selects everything. When passing a workflow variable, fail fast: --labels="ci=${CI_LABEL:?}".

• Simple Go templates in metadata.labels and metadata.tags are rendered before selection by default (templates are processed unless disabled). With templates disabled, or with --process-templates=false, the raw '{{ ... }}' text is compared, so it matches neither ci=auto nor ci=manual.

• Deleted components are filtered the same way, using their metadata from the base ref. --exclude-locked also drops deleted components that were locked in the base ref.

For full examples, read references/native-ci.md.