The Terraform CI discipline — why plan-on-PR is the right pattern

Terraform CI has a single shape: the plan runs on every pull request, the apply runs only on the default branch after the plan has been reviewed. Everything else in this Part - format, lint, security scans, integration tests, plan-as-artifact - exists to make that boundary safe. Get the boundary wrong and the rest of the discipline loses its meaning, because a CI system that can both plan and apply is a CI system that can change production from a pull-request merge.

The plan-on-PR pattern

The pull request is where the change is described, where reviewers are assigned, and where the conversation about the change happens. The plan is the content of that conversation: a concrete, line-by-line account of what the change will do to infrastructure. Posting the plan on the PR converts the review from “please review my code” into “please review this list of resources that will be created, modified, or destroyed”.

The canonical shape:

flowchart LR
    A[Pull request opened] --> B[Plan job runs in CI]
    B --> C[Plan output posted as PR comment]
    C --> D[Reviewer reads code and plan]
    D --> E{Approved?}
    E -->|no| F[Author revises]
    F --> A
    E -->|yes| G[Merge to default branch]
    G --> H[Apply job runs on default branch]

The plan job is allowed to read state but is forbidden from writing it. The apply job is allowed to write state but is forbidden from running on a pull request. The boundary is enforced by the CI system and the runner’s credentials, not by convention.

The apply boundary

The reason the apply does not run on the pull request is not operational inconvenience; it is a chain-of-trust problem. An apply is a write to production infrastructure. The trust required to perform that write comes from three sources: a reviewed pull request, a passing CI pipeline, and an identity authorised to mutate state. The pull-request event provides the first; the protected default branch provides the second; the runner’s short-lived credentials provide the third.

If apply runs on the pull request, a malicious or careless contributor who opens a PR can have infrastructure changes applied before a reviewer has seen the plan. The state is mutated, the audit log names a runner identity, and the review becomes retroactive. This is the canonical supply-chain failure mode for Terraform repositories.

What each job needs

The two jobs have asymmetric requirements:

The asymmetry is the point. A reviewer who approves a PR is approving a plan, not an apply. The apply is a separate event, gated by a separate identity, and recorded in a separate audit entry. Conflating them collapses the review boundary into the merge button, which is exactly the failure mode the pattern is designed to prevent.

Production discipline

1. Plan on every PR, apply on default branch. This is the default. Departures from it require a written exception reviewed by the platform team.
2. State read access is fine on PRs; state write access is not. Configure separate IAM roles for the plan and apply jobs.
3. The plan that is reviewed must be the plan that is applied. Saving the plan as an artifact and applying that artifact, rather than re-planning, is the contract (covered in lesson L-06).
4. Apply jobs run on protected environments with required reviewers. A direct terraform apply from a developer laptop is a CI bypass and an audit-trail break.

Cross-course references

• Terraform for Production Sysadmins - Part IX (State) covers remote state backends, which the plan job reads from and the apply job writes to.
• Terraform for Production Sysadmins - Part XII (StateLocking) covers state locking, which is what prevents two apply jobs from racing each other.
• This course, Part XLII (Secrets) - short-lived OIDC credentials are the standard way to give plan and apply jobs the access they need without storing long-lived cloud keys.
• This course, Part XLVIII (Conditions) - environment protection rules gate the apply job behind required reviewers.

Quiz