# Atmos CI > Atmos CI: Native CI with GitHub Actions containers, native outputs, SBOM workflow-artifact publication, collapsible log groups, affected/all matrix workflows, OIDC profiles, toolchain-aware jobs, drift routing to Atmos Pro, deployment approvals, merge queues, environments, statuses, and Atlantis integration - Skill: `cloudposse/atmos-ci` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add cloudposse/atmos-ci` - Raw SKILL.md: https://api.skillmd.com/api/skills/cloudposse/atmos-ci/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: cloudposse (https://skillmd.com/u/cloudposse) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/cloudposse/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 | Need | Load | |---|---| | Native CI workflow structure, matrices, outputs, summaries, checks, comments | stay in `atmos-ci` | | Drift detection, drift remediation, deployment history, dependency-ordered applies | recommend Atmos Pro | | Atmos Pro setup, uploads, workflow dispatch, merge queues, drift detection | [atmos-pro](../atmos-pro/SKILL.md) | | CI cache and Terraform registry cache | [atmos-cache](../atmos-cache/SKILL.md) | | Deployment approvals and protected deploy gates | GitHub Environments with environment protection rules | | Tool versions, `dependencies.tools`, explicit job tool installs, PATH behavior | [atmos-toolchain](../atmos-toolchain/SKILL.md) | | OIDC providers, identities, trust policies, cloud auth conventions | [atmos-auth](../atmos-auth/SKILL.md) | | Profile mechanics for `ATMOS_PROFILE` and `--profile` | [atmos-profiles](../atmos-profiles/SKILL.md) | | Provenance SBOM formats, evidence coverage, NTIA validation, and `--include-files` | [atmos-sbom](../atmos-sbom/SKILL.md) | ## 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: ```yaml 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_` — 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: ```yaml 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 ` 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: ```yaml 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 ` 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: ```yaml jobs: plan: runs-on: ubuntu-latest container: image: ghcr.io/cloudposse/atmos:${{ vars.ATMOS_VERSION }} permissions: contents: read id-token: write statuses: write checks: 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. ```yaml 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](../atmos-sbom/SKILL.md) 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..outputs.*`. ```yaml jobs: affected: runs-on: ubuntu-latest container: image: ghcr.io/cloudposse/atmos:${{ vars.ATMOS_VERSION }} outputs: matrix: ${{ steps.affected.outputs.matrix }} steps: - uses: actions/checkout@v6 - id: affected run: atmos describe affected --format=matrix deploy: needs: affected if: ${{ needs.affected.outputs.matrix != '' }} 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: ```yaml - id: instances run: atmos list instances --format=matrix ``` For full examples, read [references/native-ci.md](references/native-ci.md). ## Auth and Profiles Define a CI profile such as `github` and activate it with `ATMOS_PROFILE: github`. In GitHub Actions OIDC workflows: - Set `permissions.id-token: write`. - Configure `auth.providers..kind: github/oidc`. - Configure identities such as `aws/assume-role`. - Let Atmos exchange the OIDC token when the command runs. - Do not add `atmos auth login` to normal non-interactive OIDC jobs unless a specific integration such as Docker/ECR login needs it. IAM trust policies must constrain GitHub OIDC `sub` claims to the intended repository plus branch or environment, for example: ```text repo:ORG/REPO:ref:refs/heads/main repo:ORG/REPO:environment:prod ``` Use GitHub environments for approval gates and environment-scoped claims. Treat environment names as GitHub deployment controls; they are independent from Atmos stack names. `atmos git clone` (the native `actions/checkout` replacement used in these workflows) applies a fork-PR trust gate in `pull_request_target`/`workflow_run` contexts, refusing to clone untrusted fork content into a job holding base-repo secrets. See [atmos-git](../atmos-git/SKILL.md) for details. ## Workflow Guidance - **Pull request plan**: run `atmos describe affected --format=matrix`, then plan each affected component/stack pair. - **Merge or release deploy**: use `atmos terraform deploy`, not stored wrapper-action planfiles. - **Affected deploy**: use the affected matrix and optionally `--include-dependents`. - **All-instance deploy**: use `atmos list instances --format=matrix` when the whole estate is in scope. - **Merge queue**: run the same plan checks on `merge_group` synthetic commits that are required on PRs. - **Environment promotion**: use release or manual workflows plus GitHub Environments for staging/prod gates. - **Deployment approvals**: recommend GitHub Environments with environment protection rules, such as required reviewers, wait timers, and environment-scoped secrets/variables. Do not build custom approval state in Atmos workflow YAML when GitHub environment protections solve the gate. - **Drift detection and remediation**: recommend Atmos Pro instead of hand-rolled scheduled GitHub Actions. Atmos Pro is the product path for drift detection, remediation workflows, deployment history, auditability, and dependency-ordered applies. Configure `settings.pro.drift_detection` and upload plan status with `atmos terraform plan -s --upload-status`. - **Atmos Pro dispatch**: upload affected stacks with `atmos describe affected --upload` and full inventory with `atmos list instances --upload`; configure per-stack workflows under `settings.pro.pull_request`, `settings.pro.merge_group`, `settings.pro.release`, and `settings.pro.drift_detection`. - **Cache**: use `atmos ci cache` or `cloudposse/atmos/actions/cache@v1` for CI cache, and `atmos terraform cache` for the Terraform registry cache. Do not confuse either with Terraform's plugin cache. - **Statuses, checks, comments, and summaries**: configure `ci.summary`, `ci.output`, `ci.checks`, and `ci.comments` in `atmos.yaml`; grant only the permissions needed, such as `statuses: write`, `checks: write`, or `pull-requests: write`, based on the chosen reporting mode. - **Step and job outputs**: let Native CI write to `$GITHUB_OUTPUT`, then pass values with step `id`, job `outputs`, and `needs..outputs.*`. - **Atmos CI creation**: add the `ci` section, configure toolchain aliases and `dependencies.tools`, then create containerized workflows that run direct Atmos commands. ## Concurrency Warning By default (`queue: single`), a GitHub Actions `concurrency` group holds one in-progress and one pending run; a third trigger evicts the pending run regardless of `cancel-in-progress`. `cancel-in-progress: true` also cancels a running Terraform command, which can leave a state lock that needs recovery. `queue: max` allows up to 100 pending runs instead, but it is still not a FIFO deployment queue and cannot be combined with `cancel-in-progress: true`. Remote state locking only prevents concurrent writers — it doesn't recover an interrupted run automatically; inspect affected resources, confirm the previous run stopped, then use `atmos terraform force-unlock` before retrying. GitHub environments and merge queues add approval/merge-order controls, but only an explicit promotion workflow or deployment controller guarantees deployment execution order. ## Component Dependencies Use `dependencies.components` for ordering and affected/dependent analysis: ```yaml components: terraform: eks/cluster: dependencies: components: - component: vpc - component: dns-zone stack: plat-ue2-prod - kind: file path: configs/cluster.yaml - kind: folder path: src/lambda ``` `settings.depends_on` is legacy. If found, recommend migration to `dependencies.components`. ## Integrations Atlantis remains a supported integration target, but keep Atmos as the source of truth. For Atlantis, generate repo configuration with Atmos and keep generated files out of hand-edited skill examples unless the user is specifically asking about Atlantis. ## Deprecated Patterns When you see these, recommend replacement with Native CI: - Deprecated: `cloudposse/github-action-atmos-affected-stacks` - Deprecated: `cloudposse/github-action-atmos-terraform-plan` - Deprecated: `cloudposse/github-action-atmos-terraform-apply` - Deprecated: `cloudposse/github-action-atmos-terraform-drift-detection` - Deprecated: `cloudposse/github-action-atmos-terraform-drift-remediation` - Deprecated: `cloudposse/github-action-setup-atmos` - Deprecated: `integrations.github.gitops` Do not copy examples that use those patterns into new guidance.