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 separate setup steps. The image already includes atmos, its toolchain, and the Docker CLI, so Docker-backed Atmos commands can use the runner-provided Docker socket directly. 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.