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

Bash

+------------------------------------------------+
| 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)

Bash

helm repo add runatlantis https://runatlantis.github.io/helm-charts
helm install atlantis runatlantis/atlantis \
  --set github.user=razorpay-infra-bot \
  --set github.token=$GITHUB_TOKEN \
  --set github.webhookSecret=$WEBHOOK_SECRET

atlantis.yaml Configuration

YAML

# atlantis.yaml at the repo root — tells Atlantis where projects live
version: 3
projects:
  - 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

Bash

# A reviewer types these directly as PR comments — Atlantis listens for them
 
atlantis plan          # re-runs plan for every project changed in the PR
atlantis plan -p prod-vpc   # re-runs plan for one specific named project only
atlantis apply          # applies every project that has been planned and approved
atlantis apply -p prod-vpc  # applies just one specific project

Locking — Preventing Concurrent Applies

COMMON MISTAKE / WARNING
Common 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

YAML

workflows:
  default:
    plan:
      steps:
        - run: tflint                # lint BEFORE plan, fail fast on bad syntax
        - init
        - plan
    apply:
      steps:
        - apply

Atlantis 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