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.

Experimental

Configuration

atmos.yaml

components:
  terraform:
    planfiles:
      # Stores are tried in priority order
      priority:
        - "github"
        - "s3"
        - "local"

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

        s3:
          type: aws/s3
          options:
            bucket: "my-terraform-planfiles"
            prefix: "atmos/"
            region: "us-east-1"

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

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

tip

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

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:

1. Downloads the stored planfile bundle from storage
2. Verifies SHA256 integrity checksums
3. Generates a fresh plan against current infrastructure
4. Performs semantic comparison between stored and fresh plans
5. If plans match: Applies the verified plan
6. If plans differ: Fails with a drift detection error

This ensures that exactly what was reviewed during the plan phase gets applied, with no silent infrastructure drift.

Plan Verification

The deploy command uses semantic plan comparison — not naive text diff. It compares the JSON plan structures to detect meaningful differences while ignoring cosmetic changes.

If drift is detected, the deploy fails with a clear error showing what changed since the plan was created.

CLI Commands

Planfile Commands

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

Planfile Reference

Related

• Native CI Overview - Feature overview
• Native CI Overview - Feature overview
• CI Configuration - Full configuration reference
• atmos terraform planfile - CLI commands