Atlantis — Terraform Pull Request Automation for Teams

Introduction

Atlantis is a self-hosted server that listens to Git webhooks, runs Terraform/OpenTofu in response to pull-request comments, and streams the output back as a comment. It gives teams a shared, audited, chat-ops workflow for infrastructure changes without giving every developer direct AWS/GCP credentials.

What Atlantis Does

• Receives GitHub, GitLab, Bitbucket, or Gitea webhooks on PR open/sync/comment
• Clones the PR branch into a workspace and runs plan/apply
• Posts the plan output back as a PR comment, with collapsible diff
• Locks the state so only one PR can apply to a given workspace at a time
• Enforces OPA/Conftest policies via server-side policy checks before apply

Architecture Overview

Atlantis is a single Go binary, typically deployed as a Kubernetes Deployment or a systemd unit behind TLS. It maintains a per-repo/per-workspace lock in BoltDB (or Redis in HA), shells out to terraform/tofu binaries it downloads per-project, and uses your VCS API for comment posting. Sensitive AWS credentials live on the Atlantis host via IRSA / workload identity, not in developer laptops.

Self-Hosting & Configuration

• Helm chart: helm install atlantis runatlantis/atlantis -f values.yaml
• atlantis.yaml per repo defines projects, workspaces, terraform version, workflow hooks
• server-side-config lets ops teams lock down what users can override per-repo
• Secrets: webhook secret, VCS token, cloud credentials via env or mounted files
• HA: share BoltDB via Redis + run multiple replicas behind a load balancer

Key Features

• PR-native workflow — no special CI syntax; operators comment atlantis plan
• State locking prevents concurrent applies clobbering each other
• Policy-as-code via Conftest/OPA gates applies at plan time
• Works with Terraform, OpenTofu, Terragrunt, and custom workflow hooks
• Self-hosted — infra credentials never leave your network

Comparison with Similar Tools

• Terraform Cloud / HCP — SaaS equivalent; costlier, great UI, less control
• Spacelift / env0 / Scalr — commercial SaaS with richer policies and dashboards
• tfmigrate / tf-controller — niche GitOps operators; narrower scope
• Crossplane — Kubernetes CRDs instead of PR workflow; different paradigm
• Digger — OSS alternative running inside GitHub Actions; less mature locking

FAQ

Q: Does Atlantis run apply automatically? A: No. By default apply requires a human comment and PR approval; both are configurable.

Q: Can one server serve many repos? A: Yes. --repo-allowlist scopes repositories; atlantis.yaml per repo defines workspaces.

Q: How do I restrict who can apply? A: Use --require-approval plus allowed_workflows in server-side config and VCS CODEOWNERS.

Q: Is Terragrunt supported? A: Yes, via terragrunt_version and a workflow that calls terragrunt plan instead.

Sources

• https://github.com/runatlantis/atlantis
• https://www.runatlantis.io