What Is Atlantis?
Atlantis is a self-hosted bot that lives in front of your Terraform repository and runs Terraform for you whenever someone opens a pull request. Instead of an engineer running terraform plan on their own laptop and pasting the output into a Slack message for review, Atlantis runs the plan itself and posts the exact output as a comment directly on the pull request — where every reviewer can see it, right next to the code change that caused it.
Think of Atlantis as a very disciplined coworker who refuses to let anyone apply infrastructure changes without first showing everyone the diff in writing, getting an actual approval, and then only running apply when someone explicitly types the magic words in a comment.
At Razorpay, before Atlantis, infrastructure pull requests were approved based on reading the .tf file diff alone — which tells you what changed in the code, but not what will actually happen in AWS. After adopting Atlantis, every PR shows the real terraform plan output as a comment before anyone approves. Reviewers caught several near-misses in the first month alone — changes that looked harmless in the diff but would have force-replaced a production RDS instance.
How Atlantis Fits Into Your Workflow
+------------------------------------------------+| 1. Engineer opens a Pull Request || changing a .tf file |+------------------------------------------------+ | GitHub webhook fires to Atlantis | v+------------------------------------------------+| 2. Atlantis runs `terraform plan` automatically || and posts the FULL output as a PR comment |+------------------------------------------------+ | Reviewer reads the plan, approves the PR | v+------------------------------------------------+| 3. Reviewer comments: "atlantis apply" |+------------------------------------------------+ | v+------------------------------------------------+| 4. Atlantis runs `terraform apply`, posts the || result, and the PR can now be merged |+------------------------------------------------+Installing Atlantis on Kubernetes (Helm)
helm repo add runatlantis https://runatlantis.github.io/helm-chartshelm install atlantis runatlantis/atlantis \ --set github.user=razorpay-infra-bot \ --set github.token=$GITHUB_TOKEN \ --set github.webhookSecret=$WEBHOOK_SECRETatlantis.yaml Configuration
# atlantis.yaml at the repo root — tells Atlantis where projects liveversion: 3projects: - name: prod-vpc dir: environments/prod/vpc # which folder this project covers workflow: default apply_requirements: [approved] # apply is blocked until a reviewer approves - name: prod-ecs dir: environments/prod/ecs-service workflow: default apply_requirements: [approved]Plan and Apply via PR Comments
# A reviewer types these directly as PR comments — Atlantis listens for them atlantis plan # re-runs plan for every project changed in the PRatlantis plan -p prod-vpc # re-runs plan for one specific named project onlyatlantis apply # applies every project that has been planned and approvedatlantis apply -p prod-vpc # applies just one specific projectLocking — Preventing Concurrent Applies
COMMON MISTAKE / WARNINGCommon mistake to avoid: without any lock, two open PRs touching the same Terraform directory could both run `apply` and silently overwrite each other's state changes. Atlantis automatically locks a project's working directory the moment a plan runs on it — any other PR touching the same directory must wait until the first PR is merged or closed.
Custom Workflows
workflows: default: plan: steps: - run: tflint # lint BEFORE plan, fail fast on bad syntax - init - plan apply: steps: - applyAtlantis vs GitHub Actions for Terraform
| Atlantis | GitHub Actions | |
|---|---|---|
| Hosting | Self-hosted (you run the server) | Fully managed by GitHub |
| Workflow | PR-comment driven (atlantis apply) |
YAML pipeline, runs on merge/push events |
| Locking | Built-in, automatic per directory | You must build it yourself (e.g., with DynamoDB) |
| Best for | Teams wanting an interactive PR-based approval loop | Teams already standardised on GitHub Actions for everything |
Quick Reference
| Command (as PR comment) | What It Does |
|---|---|
atlantis plan |
Plans every changed project in the PR |
atlantis apply |
Applies every planned, approved project |
atlantis unlock |
Manually releases a stuck project lock |
| Error | Root Cause | Fix |
|---|---|---|
This project is currently locked |
Another open PR holds the lock on the same directory | Wait for that PR to merge/close, or have an admin run atlantis unlock |
| Atlantis never comments on a new PR | Webhook not configured or wrong secret | Re-check the GitHub webhook URL and secret against the Atlantis server config |
apply_requirements not met |
PR lacks the required approval | Get the PR approved by a reviewer before commenting atlantis apply |
| Plan succeeds but apply fails with credential errors | Atlantis server's IAM role lacks permissions for the new resource type | Update the IAM policy attached to the Atlantis server/pod |