# 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

**File:** `atmos.yaml`

```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[Read more](/cli/commands/terraform/planfile)

## Related

- [Native CI Overview](/ci) - Feature overview
- [Native CI Overview](/ci) - Feature overview
- [CI Configuration](/cli/configuration/ci) - Full configuration reference
- [`atmos terraform planfile`](/cli/commands/terraform/planfile) - CLI commands