Atlantis

Terraform hub

Atlantis is an open-source tool that automates Terraform pull request workflows — running terraform plan automatically when a PR is opened and posting the output as a comment, then running terraform apply when an approved reviewer comments 'atlantis apply'.

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

Frequently Asked Questions

What problem does Atlantis solve compared to running terraform apply from a laptop?

Running Terraform locally means state and plan output live only on one engineer's machine, with no audit trail of who approved what change before it was applied, and no guarantee the applied plan matches what was reviewed. Atlantis moves the whole plan/apply cycle into the pull request itself — the plan output is visible to every reviewer as a PR comment, and apply only runs after an explicit approval comment, creating a reviewable, auditable trail tied to Git history.

What's a common gotcha when running Atlantis in production?

Not locking workspaces properly, letting two PRs targeting the same Terraform state run plans concurrently — the second apply can then act on stale state and cause conflicts or unexpected resource changes. Atlantis handles locking automatically per working directory, but teams that split state incorrectly (or disable locking to unblock a stuck PR) reopen exactly the race condition Atlantis was meant to prevent.