Skip to main content

Setup Atmos

Two ways to make atmos available in your GitHub Actions workflows: run the job inside the official Atmos container image (recommended), or install the binary on a runner with the setup-atmos action.

Recommended: use the container image

For most workflows, the simplest path is to run the job inside the official Atmos container and skip a separate setup step. The image already includes atmos plus its toolchain, so the workflow reduces to checkout + run an atmos command. See the Native CI page for end-to-end examples.

jobs:
  deploy:
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/cloudposse/atmos:${{ vars.ATMOS_VERSION }}
    steps:
      - uses: actions/checkout@v6
      - run: atmos terraform deploy vpc -s prod

We don't publish a latest tag — pin to a specific version via a repository variable (e.g. vars.ATMOS_VERSION).

Setup Atmos Action​

When the container approach doesn't fit — for example, when other steps need tools that aren't in the Atmos image, or when you want to run on a self-hosted runner with a specific OS — install the atmos binary onto the runner with cloudposse/github-action-setup-atmos:

.github/workflows/example.yaml
on:
  workflow_dispatch:
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Setup Atmos
        uses: cloudposse/github-action-setup-atmos
        with:
          # Version can be pinned but defaults to latest if not specified
          atmos-version: 1.88.0

      - run: atmos terraform deploy vpc -s prod

For native CI integration patterns (job summaries, output variables, status checks, planfile storage, matrix workflows, OIDC auth), see the Native CI page.