Terraform CI/CD — Automating Plan and Apply with GitHub Actions

Overview and What You Will Learn

Manually running terraform apply from your laptop is fine when you are the only engineer touching the infrastructure. The moment your team grows to three people, it stops being fine — two engineers can apply at the same time without realising it, nobody has a record of who changed what and why, and the only way to review a change is to trust that whoever ran it copy-pasted the real plan output into Slack. A CI/CD pipeline for Terraform GitHub Actions fixes all three problems at once: every change goes through a pull request, every plan is visible to every reviewer, and apply only ever runs from one consistent, audited environment — never from anyone's laptop.

By the end of this lab you will be able to:

• Build a GitHub Actions workflow that runs terraform plan automatically on every pull request
• Authenticate to AWS using OIDC — with zero long-lived access keys stored anywhere
• Post the plan output as a readable PR comment for reviewers
• Run terraform apply automatically on merge to main, gated behind an environment protection rule
• Cache Terraform providers to keep pipeline runs fast
• Add terraform fmt, tflint, and a security scanner to the pipeline before any plan runs

Why This Matters in Production

At PhonePe, before the platform team automated Terraform, every infrastructure change followed the same informal ritual: an engineer would run terraform plan locally, paste the output into a Slack thread, wait for a thumbs-up emoji from a teammate, then run terraform apply from their own laptop. This worked until it didn't — an engineer once applied a change while disconnected from the office VPN, against credentials cached from a different AWS profile than the one shown in the Slack-pasted plan. The infrastructure that got created did not match what anyone had reviewed. After that incident, every apply in the company runs exclusively through GitHub Actions, using a service identity with OIDC — no engineer's laptop credentials can reach production Terraform state anymore, by design, not by policy memo.

Core Principles

The Terraform GitHub Actions Pipeline

Detailed Step-by-Step Practical Lab

Step 1 — Set Up OIDC Trust Between GitHub and AWS

OIDC lets GitHub Actions request short-lived AWS credentials directly — no access key or secret key is ever stored as a GitHub secret. First, create the trust relationship in AWS:

Note

Security note: that StringLike condition is the entire security boundary of OIDC. If you write "repo:*:*" instead of your exact repository name, you have just granted every public GitHub Actions workflow on Earth the ability to assume this role. Always scope it to your exact org/repo, and to specific branches if apply permissions need to be tighter than plan permissions.

Step 2 — Write the Plan Workflow (Runs on Every PR)

Step 3 — Write the Apply Workflow (Runs on Merge to Main)

In GitHub's repository settings, the production environment is configured with required reviewers — meaning even after the PR merges, a designated approver must click "Approve" inside GitHub's Environments tab before this job actually runs apply. This is a second, independent gate from the PR review itself.

Step 4 — Cache Terraform Providers for Faster Runs

Note

Tip from a senior engineer: without this cache, every single pipeline run re-downloads the AWS provider plugin — which is over 400MB. On a busy repo with twenty PRs a day, that is gigabytes of redundant network traffic and minutes of wasted CI time, every single run.

Step 5 — Handle Multiple Environments with a Matrix

This runs the plan job three times in parallel — once per environment — instead of writing three nearly-identical workflow files.

Step 6 — Add Security Scanning Before Plan

Step 7 — Pin the Terraform Version Consistently

Production Best Practices and Common Pitfalls

• Never let the plan job have write access to AWS. The IAM role assumed during plan should be read-only where possible (or at minimum, scoped tightly) — plan runs on every PR from every contributor, including ones whose changes haven't been reviewed yet. Save write/apply permissions for the separate apply workflow's role.

• Use GitHub Environments for the approval gate, not just branch protection. Branch protection controls who can merge code. A GitHub Environment with required reviewers controls who can authorize the actual apply — these are two different gates, and you want both.

• Restrict the OIDC trust policy to your exact repo and branch. A loosely scoped sub claim is the single most common OIDC misconfiguration — always test that another repository genuinely cannot assume your role before trusting it in production.

• Treat continue-on-error: true on the plan step carefully. It is there so the PR comment shows the actual error instead of GitHub Actions just showing a red X with no detail — but you must explicitly fail the job afterward, or a broken plan will silently appear to pass.

Quick Reference and Troubleshooting Commands