GitHub Actions

Use GitHub Actions to plan infrastructure changes on pull requests, deploy after review, and run jobs across the components in your stacks. Atmos handles the CI reporting, planfile verification, and component selection directly through its native commands.

Get Started

Run workflows in the Atmos container or install the CLI with Setup Atmos. Pin ATMOS_VERSION to a specific release; the container image has no latest tag. Enable native CI, then configure authentication and permissions.

Start with Plan on Pull Request and Apply on Merge. Configure planfile storage to verify the reviewed plan before applying. For larger projects, use affected-component matrices to limit work to changed infrastructure.

Workflow Guides

Setup Atmos

Install Atmos in your GitHub Action workflows

Plan on Pull Request

Review infrastructure changes before merging a pull request. Run an Atmos plan in GitHub Actions and publish the results as job summaries, checks, and pull request comments.

Apply on Merge

Deploy infrastructure after a change merges. Atmos can compare the new plan against the plan reviewed in the pull request before applying it.

Deploy Affected Components

Run CI jobs only for component instances affected by a change. Atmos produces the GitHub Actions matrix from your stacks and Git changes.

Deploy All Components

Run a workflow across every component instance in your stacks. Generate the job matrix from Atmos instead of maintaining a separate inventory in your workflow.

Deployment Approvals

Require approval before deploying production infrastructure. GitHub environments provide approval gates and environment-specific credentials while Atmos selects and deploys the stack.

Authentication & Permissions

Configure GitHub permissions and cloud authentication for Atmos CI workflows.

Validate Workflows

Catch mistakes in GitHub Actions workflows before running infrastructure commands. Atmos validates workflow syntax and can report problems as inline annotations in CI.

Working Examples

Two reference repositories you can clone and adapt — both include atmos.yaml, stack configuration, components, and full workflows. They build on the patterns above with use-case-specific design patterns (preview environments, image promotion, label gating).

Basic Example   Matrix Example

Caching the Toolchain

Every CI job reinstalls the same toolchain (Terraform, Helm, and friends). The build cache restores the Atmos cache root — which includes the toolchain install path — at the start of a job and saves it at the end, using the same GitHub Actions cache store that actions/cache uses. A warm cache turns a multi-minute toolchain install into a near-instant restore.

The most secure, lowest-boilerplate wiring is the actions/cache composite: Atmos derives the cache key and paths, native actions/cache does the storage, and no runtime token is exposed to your job.

.github/workflows/plan.yml

    steps:
      - uses: actions/checkout@v6

      - uses: cloudposse/atmos/actions/cache@v1   # pin to a release or SHA

      - run: atmos toolchain install              # near-instant on a cache hit
      - run: atmos terraform plan vpc -s prod

Prefer fully automatic caching? Set ci.cache.auto: both in atmos.yaml and Atmos restores on start and saves on exit for every invocation — no extra workflow steps:

atmos.yaml

ci:
  cache:
    enabled: true     # master switch (required)
    auto: both        # restore on start AND save on end

You can also drive the cache explicitly with the atmos ci cache subcommands (restore, save, paths, list, delete). The cache key defaults to a hash of the toolchain lockfile plus OS/arch with a prefix restore-key fallback, mirroring actions/cache; entries are write-once, so an exact hit skips the save. See the cache configuration reference for keys, paths, and the four GitHub Actions integration options with their security trade-offs.

SBOM Artifacts

Running atmos sbom generate --upload uses the detected native CI provider to retain the generated SBOM with the CI run. In GitHub Actions, this is a workflow artifact, not a Dependency Graph import. GitHub's SBOM REST API can export or request a GitHub-generated SPDX report, but it does not accept an arbitrary submitted SBOM. Add github-runtime before the command so Atmos can access the runtime API for Actions artifacts.

- 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 }}

Migrating Existing Workflows

The older Terraform wrapper actions have native command equivalents. See Migrate from Legacy Actions to update an existing workflow.