# 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](/integrations/github-actions/setup-atmos). Pin `ATMOS_VERSION` to a specific release; the container image has no `latest` tag. Enable [native CI](/ci#quick-start), then configure [authentication and permissions](/integrations/github-actions/authentication).

Start with [Plan on Pull Request](/integrations/github-actions/plan-on-pull-request) and [Apply on Merge](/integrations/github-actions/apply-on-merge). Configure [planfile storage](/ci/planfile-storage) to verify the reviewed plan before applying. For larger projects, use [affected-component matrices](/integrations/github-actions/deploy-affected) to limit work to changed infrastructure.

## Workflow Guides

**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[Read more](https://github.com/cloudposse-examples/atmos-native-ci)
 
Matrix Example[Read more](https://github.com/cloudposse-examples/atmos-native-ci-advanced)

## 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.**

**File:** `.github/workflows/plan.yml`

```yaml
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:

**File:** `atmos.yaml`

```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`](/cli/commands/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](/cli/configuration/ci/cache) 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.

```yaml
- 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](/ci/migrate-legacy-actions) to update an existing workflow.