Planfile Storage

Planfile storage enables the plan-then-deploy workflow in CI. When configured, atmos terraform plan uploads planfiles to storage, and atmos terraform deploy downloads and verifies them before applying.

Configuration

atmos.yaml

components:
  terraform:
    planfiles:
      # Drift verification on `deploy`: fail (default under CI) | warn | off
      verify: fail

      # Select the first available store in priority order
      priority:
        - "github"
        - "s3"
        - "local"

      # Named stores
      stores:
        github:
          type: github/artifacts
          options:
            retention_days: 7

        s3:
          type: aws/s3
          # Optional: authenticate the store with a specific Atmos Auth identity,
          # independent of the component's identity (see Store Identity below).
          identity: aws-backend
          options:
            bucket: "my-terraform-planfiles"
            prefix: "atmos/"
            region: "us-east-1"

        local:
          type: local/dir
          options:
            path: ".atmos/planfiles"

An explicit default store takes precedence over priority. Otherwise, the first available configured name in priority is selected; names absent from stores are skipped. GitHub artifacts require a token. For plan uploads, priority selection also requires ACTIONS_RUNTIME_TOKEN and ACTIONS_RESULTS_URL; downloads from completed runs can use the GitHub API token alone. S3 uses the AWS credential chain or the selected Atmos identity. These availability checks do not verify remote bucket permissions. An unknown explicit default, an exhausted priority list, or a selected store that cannot be initialized produces an error. Atmos does not silently redirect planfiles to a different backend after selection. Environment-based detection is used only when neither default nor priority is configured.

Storage Backends

Backend	Type	Best For
GitHub Artifacts	github/artifacts	GitHub Actions workflows (recommended)
S3	aws/s3	AWS-native environments, cross-provider workflows
Local	local/dir	Testing and development

Store Identity

By default, a planfile store authenticates with the component's active identity - the same one atmos terraform plan used for the Terraform run. That works when the component and the store live in the same cloud, but it breaks in a multi-cloud setup: a component that authenticates with, say, an azure/subscription identity cannot produce AWS credentials for an aws/s3 planfile bucket, so the upload fails to resolve an AWS auth context.

Set identity on a store to authenticate it with a specific Atmos Auth identity (from auth.identities), independent of the component's identity:

atmos.yaml

auth:
  identities:
    # Non-AWS identity the component authenticates with.
    azure-plan:
      kind: azure/subscription
      default: true
      # ...

    # AWS-capable identity the planfile store uses.
    aws-backend:
      kind: aws/assume-role   # or ambient, aws/permission-set, etc.
      # ...

components:
  terraform:
    planfiles:
      default: "s3"
      stores:
        s3:
          type: aws/s3
          identity: aws-backend    # store authenticates with aws-backend
          options:
            bucket: "my-terraform-planfiles"
            region: "us-east-1"

The component keeps using its own identity (azure-plan) for Terraform operations, while the S3 planfile store uses aws-backend for storage. When identity is omitted, the store inherits the component's identity (the prior behavior), so existing single-cloud setups are unchanged.

The identity must be able to authenticate the chosen backend: an aws/s3 store needs an AWS-capable identity. It is not limited to ambient, though - any AWS-capable identity kind or chain (aws/assume-role, aws/permission-set, …) is resolved through the same Atmos Auth chain as the component, not just passed through from the runner environment. This mirrors the stores.*.identity field already supported by general Atmos stores.

tip

If components.terraform.planfiles is not configured, planfile storage operations are silently skipped. CI summaries and status checks still work without planfile storage.

The one exception: explicitly requesting verification with --verify-plan (or ATMOS_TERRAFORM_VERIFY_PLAN=true) errors when planfile storage is not configured — there is no stored plan to verify against, and the flag cannot stand in for the storage settings it depends on.

Using GitHub Artifacts in GitHub Actions

The github/artifacts backend talks to the GitHub Actions Artifacts API directly — Atmos is the native client, not a wrapper around actions/upload-artifact. To do that it needs the runner's runtime credentials, ACTIONS_RUNTIME_TOKEN and ACTIONS_RESULTS_URL.

GitHub injects those into action steps (uses:) but withholds them from run: steps — a deliberate least-privilege decision. So when Atmos's own commands do the upload from a run: step, they will fail with:

GitHub Artifacts upload requires running within GitHub Actions
(ACTIONS_RUNTIME_TOKEN and ACTIONS_RESULTS_URL must be set)

Surface the credentials with the Atmos github-runtime action. With mode: env it exports the credentials to $GITHUB_ENV once, and GitHub then injects them automatically into every later run: step — Atmos's commands pick them up from the environment with no per-step wiring:

.github/workflows/atmos.yaml

steps:
  - uses: cloudposse/atmos/actions/github-runtime@v1   # pin to a release or SHA
    with:
      mode: env

  # Credentials are now in the environment of every later run step.
  - run: atmos terraform plan mycomponent -s prod --ci    # uploads the planfile to github/artifacts
  - run: atmos terraform deploy mycomponent -s prod --ci  # downloads, verifies, then applies

To keep the credentials out of unrelated steps, use the default mode: output instead: the action emits masked step outputs that you thread, via env:, only into the steps that store planfiles. This is the same github-runtime mechanism the atmos ci cache backend uses — see the cache configuration docs for the full security tradeoff between scoped (mode: output) and ambient (mode: env) credentials.

Least-privilege alternative (mode: output)

steps:
  - uses: cloudposse/atmos/actions/github-runtime@v1
    id: ghr
  - run: atmos terraform plan mycomponent -s prod --ci
    env:
      ACTIONS_RUNTIME_TOKEN: ${{ steps.ghr.outputs.runtime-token }}
      ACTIONS_RESULTS_URL:   ${{ steps.ghr.outputs.results-url }}

note

You only need this when Atmos performs the upload from a run: step. The credentials are already present inside uses: action steps, and the local/dir and aws/s3 backends don't use them at all.

How It Works

Plan Phase

When atmos terraform plan runs in CI mode with planfile storage configured:

1. Terraform generates a binary planfile
2. The planfile is bundled with the lock file into a tar archive
3. SHA256 integrity checksums are computed
4. The bundle is uploaded to the configured storage backend

Deploy Phase

When atmos terraform deploy runs in CI mode with planfile storage configured, verification is automatic:

1. Downloads the stored planfile bundle from storage
2. Verifies SHA256 integrity checksums
3. Generates a fresh plan against current infrastructure
4. Performs JSON-structural comparison between stored and fresh plans
5. If plans match: Applies the fresh plan (generated with the apply-time identity and state)
6. If plans drift: Fails the deploy (mode fail) or warns and proceeds (mode warn)

Atmos reconciles rather than replays: it applies the freshly generated plan once the diff confirms it matches what was reviewed, so the deploy uses the apply-time state and credentials while still guaranteeing no material drift. This avoids the brittleness of a saved plan — which goes stale when the state moves, and whose base credentials come from the apply environment, not the plan (so a plan built on a PR can fail to apply on merge). (To replay the stored binary directly, use --from-plan / --planfile.) Verification runs on deploy only — apply stays a thin wrapper.

Deploying across pull requests and merge queues

Stored plans are keyed by the commit that was checked out when they were created. That may be a PR head, a synthetic PR merge commit, or a merge-queue commit. A subsequent deploy can check out a different SHA even when the source files are identical. This applies to ordinary GitHub Actions workflows as well as workflows dispatched by Atmos Pro.

On GitHub Actions, deploy resolves the stored plan in this order:

1. The deploy's exact commit. An existing plan for that SHA always wins, without additional source or PR lookups.
2. The same Git source tree. Automatic plan uploads also publish a small, repository-scoped reference to the original plan, keyed by the source tree. This lets a plan created on a synthetic PR or queue commit be found after squash, merge, or rebase when the landed commit has identical source contents. The original artifact must still exist; deleting or expiring it invalidates the reference. These references are not additional plans in atmos terraform planfile list.
3. The associated PR revision. For a post-merge deploy, Atmos resolves the PR whose merge_commit_sha equals the checked-out SHA. For a merge_group run, it resolves the PR head only when GitHub's active queue entry still identifies that exact queue commit. For a PR event, it uses the head SHA from the event snapshot only when the checkout matches that head or the event's synthetic merge commit. It does not use an arbitrary PR's latest head.

Only an artifact-not-found result permits trying another source. Permission errors, corrupt artifacts, and other storage failures do not select another plan. Ambiguous post-merge PR matches are rejected. Lookup failures are logged and the existing missing-plan policy applies.

Whichever source is selected, deploy generates a fresh plan for its own checkout and compares it with the stored plan using the configured plan-diff policy. In fail mode, differences block apply; warn, off, and required keep their documented behavior. Plan equivalence does not replace any workflow approval or deployment authorization requirements.

Merge queues with multiple pull requests

A queue commit can contain several PRs. An individual PR plan is usable only if it matches the fresh plan for that stack/component in the combined checkout. If several PRs change the same component and the combined plan differs, generate and review a plan on the queue commit. Atmos does not combine individual planfiles or try different plans until one passes verification.

Rebuilt or removed queue entries cannot supply a newer PR-head plan to an old queue checkout. Source-tree references are published by automatic uploads with this version of Atmos; older plans remain available through their original commit keys and PR-head fallback. Other CI providers retain their existing behavior unless they implement source resolution. Storage-disabled workflows do not perform these lookups.

The GitHub token needs read access to source commits and pull requests:

permissions:
  contents: read
  pull-requests: read

GitHub Actions runtime token

With the github/artifacts store, the automatic download (like the upload) talks to the GitHub Artifacts runtime API, so deploy must also run after the github-runtime action surfaces ACTIONS_RUNTIME_TOKEN / ACTIONS_RESULTS_URL — see Using GitHub Artifacts in GitHub Actions above.

Plan Verification

Verification compares the JSON plan structures (terraform show -json) of the stored and fresh plans — not a naive text diff — detecting meaningful changes while ignoring cosmetic noise (sorted keys, masked sensitive values, skipped computed-hash attributes and data sources).

This semantic comparison is deliberate. A plan legitimately contains values that vary between review and apply — attributes "known after apply," computed fields, hashes, ordering, timestamps. A byte-for-byte check (or Terraform's own saved-plan apply, which any state-lineage change invalidates) would reject a plan that is still perfectly valid. Verification needs wiggle room: tolerate benign variation while still catching substantive drift — a resource added, removed, or actually changed.

It is configurable via components.terraform.planfiles.verify:

components:
  terraform:
    planfiles:
      verify: fail   # fail (default under CI) | warn | off

• fail (default under CI): fail the deploy on drift.
• warn: log the drift but proceed with the fresh plan.
• off: skip verification (and the stored-plan download).

A companion boolean, components.terraform.planfiles.required, governs whether a stored plan must exist to verify against. It defaults to tracking verify strictness (required when verification resolves to fail), so a fail-by-default CI deploy fails loudly instead of silently applying an unverified fresh plan. See Missing stored plan.

Per-run overrides: --verify-plan (force fail) and --verify-plan=false (force off); the CLI flag beats config, which beats the CI default. See atmos terraform deploy and Planfile drift verification.

CLI Commands

Planfile Commands

Manage stored planfiles with upload, download, list, delete, and show commands.

Planfile Reference

Related

• Native CI Overview - Feature overview
• CI Cache Configuration - The same github-runtime credential mechanism, in depth
• CI Configuration - Full configuration reference
• atmos terraform planfile - CLI commands