Terraform Pull Request Automation with Atlantis or Terraform Cloud

Why infrastructure changes need a pipeline

Application code usually passes through review and CI. Infrastructure code often does not. An engineer runs terraform apply from a laptop with broad credentials, the plan scrolls past in a terminal, and nobody else sees what changed. That works until the day it deletes a database, or until an auditor asks who changed the security group and why.

A Terraform CI/CD pipeline with plan on pull request and apply on merge fixes this. The plan becomes a visible, reviewable artefact, and the apply becomes an auditable event. It is one of the highest-value pieces of our Terraform and infrastructure as code service.

What good looks like

• Opening a pull request automatically produces a plan, posted as a comment.
• A named reviewer approves the code and the plan.
• Applying happens from the pipeline using scoped, short-lived credentials.
• The plan that was reviewed is the plan that is applied, or the apply is rejected if state has changed.
• Only one change per state runs at a time.
• Every apply is traceable to a pull request, an author and an approver.

The three realistic options

Atlantis

Atlantis is a self-hosted service. It receives webhooks from GitHub, GitLab, Bitbucket or Azure Repos, runs Terraform in a working directory, and comments the result. Its strengths are low cost, full control and plain configuration in a repository file. Its costs are that you run and secure it, and you scale it yourself.

HCP Terraform (Terraform Cloud)

A managed service with remote runs, state storage, run history, a UI, team permissions and policy checks. It removes the operations burden at the price of a vendor dependency and licensing that scales with usage. Check current pricing and terms before committing, as they change.

Plain CI (GitHub Actions or GitLab CI)

If you already live in one CI system, a workflow can do plan on pull request and apply on merge. You assemble locking, plan artefacts and comment formatting yourself. For teams with a single repository and a few stacks this is often enough. Our wider CI/CD pipeline service covers the principles.

How it works in practice

An Atlantis repository config

Projects declare where they live, which Terraform version to use, and what triggers a plan:

version: 3
automerge: false
projects:
  - name: prod-network
    dir: environments/prod/network
    terraform_version: v1.9.8
    autoplan:
      when_modified: ["*.tf", "../../../modules/network/**/*.tf"]
      enabled: true
    apply_requirements: [approved, mergeable]
workflows: {}

The apply_requirements line is the important one: nothing applies without an approval and a mergeable pull request. Watching module paths in when_modified ensures a module change re-plans every stack that uses it.

Credentials without stored keys

On GitHub Actions, the job assumes an AWS role through OIDC, so no long-lived keys exist to leak:

permissions:
  id-token: write
  contents: read
steps:
  - uses: aws-actions/configure-aws-credentials@v4
    with:
      role-to-assume: arn:aws:iam::123456789012:role/terraform-plan-dev
      aws-region: eu-west-1

The role ARN above uses a placeholder account number. Plan roles are read-mostly; apply roles are separate and only assumable from the protected branch or an approved environment.

Decisions and trade-offs

Apply before or after merge. Applying after merge is simpler and keeps main authoritative. Applying before merge catches failures early but can leave open pull requests holding a lock. We choose per team and write the rule down.

Autoplan everywhere or on demand. Autoplan on every push gives fast feedback but costs runner time in large monorepos. Path filters keep it sensible.

Policy as code. Adding checks to the pipeline is where Terraform security scanning fits, and cost estimation tools can sit alongside.

When not to build this yet. A solo engineer with one small stack and no compliance needs may be fine applying locally with remote state. The pipeline earns its keep when there are several contributors or any production risk.

Failure modes we avoid

• Stale plans applied. We require the apply to match the reviewed plan or re-plan.
• Lock left by a cancelled run. The runbook covers safe release.
• Over-privileged pipeline role. One admin role for everything turns a pipeline compromise into an account compromise. We split by environment and by plan versus apply.
• Fork pull requests running plans. Untrusted code could read credentials, so forks are blocked.
• Plan output leaking secrets. Sensitive values are marked and comments are limited to what reviewers need.

Choosing by team shape

The right tool often follows who will own it. A platform team that already runs Kubernetes and is comfortable operating a small service tends to prefer Atlantis, because the running cost is low and the behaviour is transparent. A team with no appetite for operating anything, or one that needs run history and role-based permissions for auditors, usually does better with HCP Terraform. A team of three engineers with a single repository often needs neither, and a well-written workflow is the honest answer. We say so in the recommendation, even when it means less work for us.

A second question is blast radius. Whichever tool you pick, split state so that one pipeline run can only touch one environment or one component. A single giant state turns every pull request into a queue.

Delivery and handover

You receive a running pipeline, configuration in your repository, a contributor guide with example pull requests, and an operations runbook. We usually onboard one stack first, then expand. See the layout it fits into in our page on multi-environment setup.

How to tell it is working

Every production change links to a pull request. Local applies stop happening, which you can verify from cloud audit logs. Plans appear within minutes of opening a pull request, and review comments focus on the infrastructure, not on how to run Terraform. To choose between the options for your team, book a consultation.

References

• Atlantis Documentation, Atlantis
• UI and VCS-driven run workflow in HCP Terraform, HashiCorp Developer
• OpenID Connect, GitHub Docs