cloudposse
diff --git a/‎.github/workflows/planfile-artifacts-e2e.yml‎
Lines changed: 126 additions & 0 deletions b/‎.github/workflows/planfile-artifacts-e2e.yml‎
Lines changed: 126 additions & 0 deletions
diff --git a/‎.github/workflows/planfile-verify-e2e.yml‎
Lines changed: 160 additions & 0 deletions b/‎.github/workflows/planfile-verify-e2e.yml‎
Lines changed: 160 additions & 0 deletions
diff --git a/‎actions/github-runtime/README.md‎
Lines changed: 26 additions & 2 deletions b/‎actions/github-runtime/README.md‎
Lines changed: 26 additions & 2 deletions
diff --git a/‎actions/github-runtime/action.yml‎
Lines changed: 8 additions & 4 deletions b/‎actions/github-runtime/action.yml‎
Lines changed: 8 additions & 4 deletions
diff --git a/‎cmd/terraform/deploy.go‎
Lines changed: 1 addition & 1 deletion b/‎cmd/terraform/deploy.go‎
Lines changed: 1 addition & 1 deletion
@@ -0,0 +1,126 @@
+# End-to-end test for the `github/artifacts` planfile store via the EXPLICIT CLI
+# (manual) path, across two separate jobs:
+#
+#   plan job   -> `atmos terraform plan --ci` uploads the planfile to GitHub
+#                 Actions Artifacts.
+#   apply job  -> explicitly `atmos terraform planfile download` the artifact
+#                 (cross-job, same run) and `atmos terraform apply --planfile=...`.
+#
+# The AUTOMATIC hook-driven flow (plan --ci upload -> deploy --ci auto download +
+# verify + apply) is tested separately in planfile-verify-e2e.yml.
+#
+# This is the one path no Go unit test can cover: the backend talks to the
+# GitHub Actions Artifacts API directly using the runner-only
+# ACTIONS_RUNTIME_TOKEN / ACTIONS_RESULTS_URL, which GitHub withholds from
+# `run:` steps. We dogfood the in-repo `actions/github-runtime` action
+# (mode: env) to surface them — exactly the wiring documented at
+# /ci/planfile-storage.
+#
+# The IaC binary is also dogfooded through the Atmos toolchain: the fixture
+# declares `dependencies.tools.opentofu` (+ `command: tofu`), so
+# `atmos terraform plan/apply` auto-installs OpenTofu and resolves it from the
+# toolchain PATH — no hashicorp/setup-terraform action required.
+name: Planfile Artifacts E2E
+
+on:
+  workflow_dispatch:
+  pull_request:
+    types: [opened, synchronize, reopened]
+    paths:
+      - 'pkg/ci/artifact/**'
+      - 'cmd/terraform/planfile/**'
+      - 'pkg/ci/plugins/terraform/**'
+      - 'actions/github-runtime/**'
+      - 'tests/fixtures/scenarios/planfile-artifacts-e2e/**'
+      - '.github/workflows/planfile-artifacts-e2e.yml'
+
+permissions:
+  contents: read
+  actions: read # Required for the GITHUB_TOKEN to list/download artifacts via the REST API.
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  # Pin the SHA so the plan upload and the apply download derive the identical
+  # planfile key across both jobs.
+  ATMOS_CI_SHA: ${{ github.sha }}
+  GITHUB_TOKEN: ${{ github.token }}
+  FIXTURE_DIR: tests/fixtures/scenarios/planfile-artifacts-e2e
+
+jobs:
+  plan:
+    name: plan (upload planfile)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Set up Go
+        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
+        with:
+          go-version-file: "go.mod"
+
+      - name: Build atmos
+        run: |
+          make build
+          echo "$PWD/build" >> "$GITHUB_PATH"
+
+      # Surface the runner's ACTIONS_* credentials to every later run step.
+      # This is the entire reason github/artifacts works from a `run:` step.
+      - name: Expose GitHub Actions runtime credentials
+        uses: ./actions/github-runtime
+        with:
+          mode: env
+
+      - name: Plan and upload the planfile
+        working-directory: tests/fixtures/scenarios/planfile-artifacts-e2e
+        run: atmos terraform plan mycomponent -s prod --ci
+
+  apply:
+    name: apply (consume planfile)
+    needs: plan
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Set up Go
+        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
+        with:
+          go-version-file: "go.mod"
+
+      - name: Build atmos
+        run: |
+          make build
+          echo "$PWD/build" >> "$GITHUB_PATH"
+
+      - name: Expose GitHub Actions runtime credentials
+        uses: ./actions/github-runtime
+        with:
+          mode: env
+
+      - name: Download the planfile uploaded by the plan job
+        working-directory: tests/fixtures/scenarios/planfile-artifacts-e2e
+        run: |
+          set -euo pipefail
+          # The named "github" store carries prefix=planfile and resolves owner/repo
+          # from GITHUB_REPOSITORY — matching exactly what the plan job's --ci upload
+          # hook wrote (planfile-<stack>--<component>--<sha>.tfplan.tar in this run).
+          # Artifacts are run-scoped, so the plan job's upload is visible here.
+          atmos terraform planfile download mycomponent -s prod \
+            --store=github -o "$RUNNER_TEMP/downloaded.planfile"
+          test -s "$RUNNER_TEMP/downloaded.planfile"
+
+      - name: Apply the downloaded planfile
+        working-directory: tests/fixtures/scenarios/planfile-artifacts-e2e
+        run: |
+          set -euo pipefail
+          # Apply exactly the plan that was reviewed in the plan job — no re-plan.
+          atmos terraform apply mycomponent -s prod --planfile="$RUNNER_TEMP/downloaded.planfile"
+          echo "Round-trip OK: planfile uploaded by the plan job was applied by the apply job."
@@ -0,0 +1,160 @@
+# End-to-end test for the AUTOMATIC native-CI planfile flow on `deploy`.
+#
+# Distinct from planfile-artifacts-e2e.yml (which exercises the *manual* CLI:
+# `planfile download` + `apply --planfile`). This workflow exercises the
+# hook-driven automatic path:
+#
+#   plan job          -> `atmos terraform plan` auto-uploads the planfile, then
+#                        `atmos terraform planfile list` asserts it landed.
+#   deploy-verify job -> `atmos terraform deploy` auto-downloads the stored plan,
+#                        runs the plan-diff, and applies the verified plan
+#                        (verification is on by default under CI).
+#   deploy-drift job  -> mutates the component so the fresh plan differs, then
+#                        asserts `deploy` FAILS on drift (verify mode fail).
+#
+# CI is auto-detected (CI/GITHUB_ACTIONS) and the fixture sets `ci.enabled: true`,
+# so the `--ci` flag is unnecessary — the commands behave natively and assert via
+# their own exit codes and structured output rather than grepping logs.
+#
+# The warn/off mode decisions are covered by unit tests (finalizeVerification,
+# ResolveVerifyMode); this workflow covers the real runner integration.
+#
+# Like the upload, the automatic download talks to the GitHub Artifacts runtime
+# API, so every job surfaces ACTIONS_RUNTIME_TOKEN/RESULTS_URL via the in-repo
+# github-runtime action. OpenTofu is dogfooded through the Atmos toolchain (the
+# fixture declares dependencies.tools.opentofu), so there is no setup-terraform.
+name: Planfile Verify E2E
+
+on:
+  workflow_dispatch:
+  pull_request:
+    types: [opened, synchronize, reopened]
+    paths:
+      - 'pkg/ci/artifact/**'
+      - 'cmd/terraform/**'
+      - 'internal/exec/terraform_verify_plan.go'
+      - 'internal/exec/terraform_plan_diff*.go'
+      - 'pkg/ci/plugins/terraform/**'
+      - 'actions/github-runtime/**'
+      - 'tests/fixtures/scenarios/planfile-artifacts-e2e/**'
+      - '.github/workflows/planfile-verify-e2e.yml'
+
+permissions:
+  contents: read
+  actions: read # GITHUB_TOKEN reads artifacts via the REST API (fallback path).
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  # Pin the SHA so the plan upload and the deploy download derive the identical
+  # planfile key across jobs.
+  ATMOS_CI_SHA: ${{ github.sha }}
+  GITHUB_TOKEN: ${{ github.token }}
+  FIXTURE_DIR: tests/fixtures/scenarios/planfile-artifacts-e2e
+
+jobs:
+  plan:
+    name: plan (upload planfile)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - name: Set up Go
+        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
+        with:
+          go-version-file: "go.mod"
+      - name: Build atmos
+        run: |
+          make build
+          echo "$PWD/build" >> "$GITHUB_PATH"
+      - name: Expose GitHub Actions runtime credentials
+        uses: ./actions/github-runtime
+        with:
+          mode: env
+      - name: Plan and upload the planfile
+        working-directory: tests/fixtures/scenarios/planfile-artifacts-e2e
+        # No --ci: GitHub Actions is auto-detected (CI/GITHUB_ACTIONS) and the
+        # fixture sets ci.enabled, so the upload hook runs natively.
+        run: atmos terraform plan mycomponent -s prod
+      - name: List the uploaded planfile
+        working-directory: tests/fixtures/scenarios/planfile-artifacts-e2e
+        # Exercises the github/artifacts List() against the real runner API and
+        # proves the upload landed, asserting the command's structured JSON output
+        # (not grepping log prose). The command already filters by component+stack
+        # +SHA, so a non-empty array means the planfile is there; an absent one
+        # renders `null`, which `length > 0` fails on.
+        run: |
+          set -euo pipefail
+          atmos terraform planfile list mycomponent -s prod --format=json \
+            | jq -e 'length > 0' > /dev/null
+
+  deploy-verify:
+    name: deploy (auto verify + apply)
+    needs: plan
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - name: Set up Go
+        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
+        with:
+          go-version-file: "go.mod"
+      - name: Build atmos
+        run: |
+          make build
+          echo "$PWD/build" >> "$GITHUB_PATH"
+      - name: Expose GitHub Actions runtime credentials
+        uses: ./actions/github-runtime
+        with:
+          mode: env
+      - name: Deploy with automatic verification
+        working-directory: tests/fixtures/scenarios/planfile-artifacts-e2e
+        # No drift: the deploy re-plans the unchanged component, the plan-diff matches
+        # the stored plan, and the verified plan is applied. No --ci, no log grep: a
+        # green deploy *proves* verification ran, because a missing stored plan now
+        # fails loudly (planfiles.required defaults to tracking the verify mode,
+        # which is fail under CI).
+        run: atmos terraform deploy mycomponent -s prod
+
+  deploy-drift:
+    name: deploy (drift fails)
+    needs: plan
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - name: Set up Go
+        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
+        with:
+          go-version-file: "go.mod"
+      - name: Build atmos
+        run: |
+          make build
+          echo "$PWD/build" >> "$GITHUB_PATH"
+      - name: Expose GitHub Actions runtime credentials
+        uses: ./actions/github-runtime
+        with:
+          mode: env
+      - name: Induce drift and expect deploy to fail
+        working-directory: tests/fixtures/scenarios/planfile-artifacts-e2e
+        # Native exit code is the contract: deploy exits non-zero on drift
+        # (ErrPlanVerificationFailed), so an inverted check needs no --ci, no
+        # captured `$?`, and no log grep.
+        run: |
+          set -euo pipefail
+          # Mutate the component so the fresh plan differs from the stored plan.
+          sed -i 's/test = "test"/test = "drifted"/' components/terraform/mock/main.tf
+
+          if atmos terraform deploy mycomponent -s prod; then
+            echo "ERROR: expected drift to block the deploy, but it succeeded."
+            exit 1
+          fi
+          echo "Drift correctly blocked the deploy."
@@ -1,8 +1,15 @@
 # Atmos GitHub Runtime action
 
 Exposes the GitHub Actions **runtime credentials** (`ACTIONS_RUNTIME_TOKEN`,
-`ACTIONS_RESULTS_URL`, …) to your `run:` steps so the Atmos-managed cache backend
-(`atmos ci cache restore` / `save`) can reach the GitHub Actions cache service.
+`ACTIONS_RESULTS_URL`, …) to your `run:` steps so the Atmos backends that talk
+to the runner's cache and artifacts services can reach them:
+
+- **Cache** — `atmos ci cache restore` / `save` (GitHub Actions cache service).
+- **Planfile storage** — `atmos terraform plan --ci` / `atmos terraform deploy`
+  / `atmos terraform planfile upload`|`download` when the `github/artifacts`
+  store is selected (GitHub Actions Artifacts service).
+
+Both read the same two env vars, so this single action serves both.
 
 ## Why this exists
 
@@ -56,6 +63,23 @@ The runtime token is always masked with `::add-mask::` regardless of mode.
   run: atmos ci cache save
 ```
 
+### Planfile storage (`github/artifacts`)
+
+The same credentials let the [`github/artifacts` planfile store](https://atmos.tools/ci/planfile-storage)
+upload/download planfiles from a `run:` step. With `mode: env` no per-step wiring is needed —
+`atmos terraform` reads the credentials from the environment automatically:
+
+```yaml
+- uses: cloudposse/atmos/actions/github-runtime@v1   # pin to a release or SHA
+  with:
+    mode: env
+- run: atmos terraform plan mycomponent -s prod --ci    # uploads to github/artifacts
+- run: atmos terraform deploy mycomponent -s prod --ci  # downloads & verifies the planfile
+```
+
+Prefer `mode: output` (the default) when you want to scope the credentials to only these steps via
+explicit `env:`, exactly as in the cache examples above.
+
 ## Versioning
 
 This action ships **inside the Atmos repository**, so the ref is an Atmos
 
@@ -2,8 +2,12 @@
 #
 # Exposes the GitHub Actions runtime credentials (ACTIONS_RUNTIME_TOKEN,
 # ACTIONS_RESULTS_URL, ...) that the runner injects only into *action* steps,
-# so a following `run:` step can use `atmos ci cache restore/save` (whose GitHub
-# backend reads them from the environment).
+# so a following `run:` step can use any Atmos command whose GitHub backend
+# reads them from the environment, namely:
+#   - `atmos ci cache restore/save` (GitHub Actions cache service)
+#   - `atmos terraform plan --ci` / `atmos terraform deploy` / `atmos terraform
+#     planfile upload|download` with the `github/artifacts` planfile store
+#     (GitHub Actions Artifacts service).
 #
 # Two modes (the runtime token is always masked with ::add-mask:: either way):
 #   - output (default): expose credentials as masked *step outputs*. You thread
@@ -13,7 +17,7 @@
 #
 # See actions/github-runtime/README.md for the security tradeoff and examples.
 name: 'Atmos GitHub Runtime'
-description: 'Expose GitHub Actions runtime credentials to run steps so `atmos ci cache` can reach the cache service.'
+description: 'Expose GitHub Actions runtime credentials to run steps so `atmos ci cache` and the `atmos terraform` github/artifacts planfile store can reach the runner cache & artifacts services.'
 author: 'Cloud Posse'
 branding:
   icon: 'unlock'
@@ -29,7 +33,7 @@ outputs:
   runtime-token:
     description: 'ACTIONS_RUNTIME_TOKEN (masked). Set ACTIONS_RUNTIME_TOKEN from this in the consuming step.'
   results-url:
-    description: 'ACTIONS_RESULTS_URL — the cache service v2 base URL used by save/restore.'
+    description: 'ACTIONS_RESULTS_URL — the cache & artifacts service v2 base URL used by cache save/restore and the github/artifacts planfile store.'
   cache-url:
     description: 'ACTIONS_CACHE_URL — legacy v1 cache URL, when present.'
   runtime-url:
 
@@ -121,7 +121,7 @@ func init() {
 		flags.WithBoolFlag("affected", "", false, "Deploy the affected components in dependency order"),
 		flags.WithBoolFlag("all", "", false, "Deploy all components in all stacks"),
 		flags.WithBoolFlag("ci", "", false, "Enable CI mode for automated pipelines (writes job summary, outputs)"),
-		flags.WithBoolFlag("verify-plan", "", false, "Verify stored planfile matches current state before applying"),
+		flags.WithBoolFlag("verify-plan", "", false, "Force planfile drift verification before applying, overriding config (use --verify-plan=false to disable)"),
 		flags.WithEnvVars("deploy-run-init", "ATMOS_TERRAFORM_DEPLOY_RUN_INIT"),
 		flags.WithEnvVars("from-plan", "ATMOS_TERRAFORM_DEPLOY_FROM_PLAN"),
 		flags.WithEnvVars("planfile", "ATMOS_TERRAFORM_DEPLOY_PLANFILE"),