A Webhook-Driven Terraform Bot
Atlantis is the most widely adopted open-source tool for Terraform GitOps. It is a self-hosted server that listens for webhook events from your Git provider (GitHub, GitLab, Bitbucket, or Azure DevOps). When a pull request touches Terraform code, Atlantis runs terraform plan and posts the output directly as a PR comment. When an authorized user approves and comments atlantis apply, Atlantis runs the apply and reports the result — all without any engineer needing direct cloud credentials on their workstation.
The Full Workflow, Step by Step
Step 1 — Open a Pull Request:
An engineer changes an EC2 instance type from t2.micro to t3.medium in main.tf and opens a PR.
Step 2 — Automatic Plan:
GitHub sends a webhook to the Atlantis server. Atlantis checks out the branch, runs terraform plan using credentials it holds server-side, and posts the output directly as a comment on the PR — the same "0 to add, 1 to change, 0 to destroy" summary an engineer would see running it locally, but visible to every reviewer without anyone needing cloud credentials of their own. The reviewer now sees not just the code diff, but the exact infrastructure impact — what will be created, changed, or destroyed. This is the critical insight: code review and impact review happen together.
Step 3 — Review and Approve:
A peer reviews both the code change and the plan output. They approve the PR in the Git UI.
Step 4 — Execute:
The PR author (or an authorized reviewer) comments atlantis apply on the PR. Atlantis runs terraform apply -auto-approve using the same plan it already generated. It cannot apply a different plan than the one that was reviewed.
Step 5 — Merge:
Atlantis reports success in a comment, optionally merges the PR automatically, and releases the directory lock.
Locking: Solving the Concurrency Problem
Without locking, two engineers could open PRs that both modify the same Terraform directory. Their plans would be generated against the same base state, but whichever apply runs second would encounter a state that the first apply already changed — potentially causing errors or, worse, silently overwriting changes.
Atlantis solves this with directory-level locking. The moment a PR triggers a plan for a specific directory (e.g., environments/prod), Atlantis locks that directory. Any other PR that tries to plan or apply the same directory gets a comment naming the PR that currently holds the lock and asking it to wait. The lock is released when the PR is merged, closed, or when someone manually runs atlantis unlock. This serializes changes to any given environment, preventing race conditions.
Atlantis Configuration: atlantis.yaml
For non-trivial repositories, you define Atlantis behavior in an atlantis.yaml file at the repo root, listing each project's directory, when it should auto-plan, and what's required before an apply is accepted. Key fields:
- dir: Which directory this project corresponds to.
- autoplan.when_modified: Atlantis only plans when files matching these patterns change — avoids unnecessary plans on unrelated file edits.
- apply_requirements: Enforces that the PR must be approved and have no merge conflicts before atlantis apply is accepted. This is policy-as-code.
Credential Model
Atlantis holds the cloud credentials (AWS IAM role, GCP service account, etc.) server-side. Engineers' workstations need no cloud credentials at all. This is a significant security improvement: you can grant Atlantis a tightly scoped IAM role with only the permissions needed for the specific Terraform modules it manages, and you can audit every action it takes through CloudTrail or equivalent.
A common interview question is: "How do you prevent a malicious or careless engineer from bypassing Atlantis and running terraform apply directly?" The answer is IAM policy. The Atlantis server's IAM role has the cloud permissions. Individual engineers' IAM users or roles should have no permissions to modify production infrastructure directly. Atlantis is not just a workflow tool — it is an access control boundary. Pair this with branch protection rules (require PR approval, no direct pushes to main) and you have defense in depth.