Atlantis — Pull Request Automation for Terraform Teams

Overview and What You Will Learn

Atlantis is a bot that lives in your infrastructure repository and runs Terraform for you whenever someone opens a pull request. It posts the terraform plan output directly as a comment on the PR, and only runs terraform apply after someone types the words atlantis apply in a follow-up comment. The entire approval loop — see the plan, approve the code, trigger the apply — happens inside GitHub, with nobody ever running Terraform from a personal laptop.

This lab goes further than just knowing what Atlantis is — it walks through standing up a real Atlantis server, wiring it to GitHub, configuring per-project workflows, and understanding exactly where it fits next to (or instead of) GitHub Actions.

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

• Install and run an Atlantis server on Kubernetes using the official Helm chart
• Configure GitHub webhooks so Atlantis receives pull request events
• Write an atlantis.yaml that defines multiple projects and per-project workflows
• Use atlantis plan and atlantis apply as PR comments to drive real infrastructure changes
• Set up required approvals and custom workflow steps, including a policy-check stage
• Decide confidently between Atlantis and GitHub Actions for your own team

Why This Matters in Production

At Razorpay, a 12-person platform team adopted Atlantis after outgrowing their GitHub Actions-only setup. The team's complaint with Actions wasn't that it didn't work — it was that engineers had to leave the PR, go check the Actions tab in a separate browser tab, scroll through raw log output, and then come back to comment their approval. With Atlantis, the entire interaction — plan output, approval, and the apply trigger — lives inside the PR itself as comments, which meant engineers actually started reading every plan line by line instead of skimming a green checkmark and approving on faith.

Core Principles

Atlantis Server Architecture

Detailed Step-by-Step Practical Lab

Step 1 — Install Atlantis on Kubernetes

INFORMATION

Security note: `orgAllowlist` is not optional in practice. Without it, your Atlantis server will happily process webhook requests claiming to be from ANY GitHub org that knows your webhook URL. Always scope it to your exact organisation.

Step 2 — Configure the GitHub Webhook

In your repository's Settings → Webhooks, point GitHub at the Atlantis server's public endpoint:

Step 3 — Write atlantis.yaml at the Repo Root

Step 4 — Drive Plan and Apply Through PR Comments

Step 5 — Locking Prevents Concurrent Applies

Step 6 — Custom Workflows with a Policy Check Stage

INFORMATION

Tip from a senior engineer: putting `conftest` (an OPA policy tool) directly in the plan workflow means a policy violation — like "no security group may allow ingress from 0.0.0.0/0" — gets caught and posted as a PR comment automatically, before any human even reviews the code. The reviewer's job becomes reviewing intent, not manually re-checking rules a machine already verified.

Step 7 — Atlantis vs GitHub Actions for Terraform

Step 8 — Atlantis vs Terraform Cloud

Production Best Practices and Common Pitfalls

• Always set apply_requirements: [approved, mergeable]. Without it, anyone who can comment on the PR — not necessarily an approved reviewer — can trigger atlantis apply. This single line is the difference between "reviewed changes only" and "anyone with comment access can change production."

• Run Atlantis itself behind your own IAM role boundaries. The Atlantis server's own AWS credentials determine what it can actually apply. If the server's role has admin access to your entire AWS account, every project in every repo it watches inherits that blast radius.

• Don't skip the orgAllowlist setting. This is the single most common Atlantis misconfiguration in the wild — an Atlantis server with an open webhook and no allowlist will process and execute Terraform from any repository that can reach its webhook URL.

• Keep staging and production on different workflows. Production projects should require policy checks and explicit approval; staging projects can move faster with a lighter workflow — don't force the same friction on both.

Quick Reference and Troubleshooting Commands