# Atmos CI > Atmos CI is an Agent Skill for devops & security published in the cloudposse/atmos repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task. Atmos CI: Native CI with GitHub Actions containers, native outputs, 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 name: `atmos-ci` - Category: [DevOps & Security](https://www.openparable.com/skill/devops-security/1) - Source: https://github.com/cloudposse/atmos/blob/HEAD/agent-skills/skills/atmos-ci/SKILL.md - Repository: cloudposse/atmos (1,334 GitHub stars when collected) ## SKILL.md # 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) | ## 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. ## 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 Do not present GitHub Actions `concurrency` groups as a FIFO deployment queue. Default concurrency allows at most one running and one pending run per group, and a newer pending run replaces an older pending run. Even queueing modes have ordering caveats. For strict deployment ordering, use GitHub merge queues, GitHub environments, an explicit promotion workflow, or an external queue/orchestrator. ## 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. --- Source: https://www.openparable.com/skill/devops-security/atmos-ci (OpenParable). Cite the canonical URL above.