Terraform in CI/CD

1Why Run Terraform in a Pipeline

Running terraform apply from laptops means: unreviewed changes, inconsistent Terraform/provider versions, powerful credentials on personal machines, no audit trail, and "it worked for me" state conflicts. A pipeline gives every infrastructure change the same path as application code: pull request → automated checks → reviewed plan → approved apply (devops-cloud/cicd/01-ci_cd_fundamentals).

2The Standard Flow

pull request opened/updated
  ├─ fmt -check, validate, tflint, security scan (checkov/trivy)       (09-testing_and_policy_as_code/)
  ├─ terraform plan -out=tfplan  (per changed unit/environment)
  ├─ post the plan summary as a PR comment; upload tfplan as an artifact
  └─ policy checks on the plan (OPA/Conftest, Sentinel)
review + approve the PR (CODEOWNERS for infra)
merge to main
  ├─ dev/staging: terraform apply tfplan (or re-plan + apply) automatically
  └─ prod: wait for manual approval (protected environment) → apply the reviewed plan
scheduled (nightly): terraform plan -detailed-exitcode on every unit → alert on drift

Apply what was reviewed: either apply the saved plan file from the PR (if nothing changed since), or re-plan on main and require the new plan to be approved before apply. Applying a fresh plan nobody looked at defeats the purpose.

3A GitHub Actions Example

name: terraform
on:
  pull_request: { paths: ["infra/**"] }
  push: { branches: [main], paths: ["infra/**"] }

permissions: { contents: read, id-token: write, pull-requests: write }

jobs:
  plan:
    runs-on: ubuntu-24.04
    defaults: { run: { working-directory: infra/live/prod/services } }
    concurrency: { group: tf-prod-services }      # one run per unit at a time
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
        with: { terraform_version: 1.9.8 }
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::111111111111:role/tf-plan-prod   # READ-ONLY role for plans
          aws-region: eu-west-1
      - run: terraform init -input=false
      - run: terraform fmt -check -recursive
      - run: terraform validate
      - run: terraform plan -input=false -no-color -out=tfplan
      - run: terraform show -no-color tfplan > plan.txt
      - uses: actions/upload-artifact@v4
        with: { name: tfplan-prod-services, path: infra/live/prod/services/tfplan }
      # post plan.txt as a PR comment (e.g. actions/github-script)

  apply:
    if: github.ref == 'refs/heads/main'
    needs: plan
    environment: production                        # required reviewers configured in repo settings
    runs-on: ubuntu-24.04
    steps:
      # checkout, setup-terraform, credentials with role tf-apply-prod (WRITE), init, download artifact
      - run: terraform apply -input=false tfplan

4Credentials

• Use OIDC federation from the CI provider to the cloud (no long-lived access keys in CI secrets).
• Separate roles: a read-only plan role (can run on PRs, including from branches) and a write apply role usable only from the protected branch/environment (IAM trust policy conditions on the OIDC sub claim, e.g. repo:acme/infra:environment:production).
• Never run plan for untrusted fork PRs with secrets available — a malicious external data source or provider could exfiltrate credentials.

env:
  AWS_ACCESS_KEY_ID: ${{ secrets.AWS_KEY }}
  AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET }}
# valid forever, copied around, admin by default

permissions: { id-token: write, contents: read }
- uses: aws-actions/configure-aws-credentials@v4
  with:
    role-to-assume: arn:aws:iam::111111111111:role/tf-plan
    aws-region: eu-west-1
# 1-hour credentials, trust limited to this repo + branch

5Monorepos: Plan Only What Changed

With many units, detect changed directories (path filters, git diff) and plan only those — plus units depending on changed shared modules. Tools: Atlantis (PR-driven plan/apply via comments, locking per directory), Terragrunt (run-all with dependency ordering), HCP Terraform, Spacelift, env0, Digger.

6Drift Detection

terraform plan -detailed-exitcode exits 0 (no changes), 2 (changes present) or 1 (error). Run it on a schedule for every unit; exit code 2 on main means reality drifted (console changes, out-of-band automation) → alert the owning team, then codify or revert (03-state_and_remote_backends/ exercise 2, incident C).

Under the HoodWhat a Saved Plan Contains▾

terraform plan -out=tfplan writes a binary file (a zip) containing the full planned changes, the prior state snapshot it was based on, the configuration, the variable values (including sensitive ones — protect the artifact), and the provider and Terraform version requirements. terraform apply tfplan executes exactly those changes without re-planning — but only if the state hasn't changed since: if another apply modified the state in between (its serial/lineage differs), Terraform refuses with "Saved plan is stale". That's the mechanism that makes "apply the reviewed plan" safe; combined with a concurrency group (one run per unit) it prevents two pipelines from racing on the same state.

⚠️ Common Pitfalls

1. Applying a plan nobody reviewed (re-plan on main without approval).
2. Long-lived admin keys in CI secrets — use OIDC + scoped roles.
3. No concurrency control — two applies on one unit.
4. Running plans for fork PRs with credentials.
5. Plan artifacts publicly downloadable — they contain variable values.
6. No drift detection — the code silently stops describing reality.

📋 Quick Reference

PR: fmt -check · validate · tflint · checkov · plan -out (read-only role) · comment plan · policy check
main: apply reviewed plan (dev auto, prod approval, write role via OIDC) · concurrency per unit
nightly: plan -detailed-exitcode (2 = drift) → alert
tools: Atlantis · Terragrunt · HCP Terraform · Spacelift

🎤 Interview Q&A

🛠️ Practice exercises

Each exercise is a file in this topic folder. Code exercises are self-checking: run them and make the checks pass.

✅ Check yourself

Source: tf_terraform_in_ci_cd_theory.md · generated by tools/build_lessons.py