Atlantis is the bridge between a Terraform repo and a pull-request workflow: open a PR, Atlantis comments terraform plan output, a reviewer comments atlantis apply to ship. The state lives in the same backend you already use; Atlantis only orchestrates the plan/apply lifecycle and the locking around it. This article covers the install, the workflow customization that matters, and the policy-checks layer we add for clients running multi-team Terraform at scale.
How to verify
systemctl status atlantis
journalctl -u atlantis -n 100
curl -fsS https://atlantis.example.com/healthz
curl -fsS https://atlantis.example.com/status
# inside a PR comment:
# atlantis plan
# atlantis apply
# atlantis unlock
The /healthz endpoint returns 200 if the process is up; /status shows pending locks across all repos. If a PR is stuck because another PR holds the lock, the unlock command in either PR releases it — that’s the most common operator chore.
What’s happening
Atlantis is a single Go binary that runs as a webhook receiver. When a PR opens or changes, the VCS posts to Atlantis; Atlantis clones the repo at the PR’s HEAD, runs terraform plan in each project directory affected by the diff, and posts the output as a PR comment. When a reviewer comments atlantis apply, Atlantis runs terraform apply against the same plan.
The locking model is per-project (or per-workspace if you use workspaces). When PR A triggers a plan in prod/networking, that project is locked; PR B’s plan in the same project waits or is rejected, depending on configuration. This is what stops two PRs from racing each other against the same state file.
The customization surface that matters: repos.yaml (server-side allow-list of repos and per-repo workflow overrides), atlantis.yaml (per-repo, declares projects and which workflow to use), and workflows (named sequences of init/plan/apply commands). For anything beyond a single-team install, you want server-side config so PRs can’t change their own workflow.
The procedure
-
Install Atlantis as a container (also available as a Helm chart):
docker run -d --name=atlantis --restart=always \ -p 127.0.0.1:4141:4141 \ -v /etc/atlantis:/etc/atlantis:ro \ -v /var/lib/atlantis:/atlantis \ -e ATLANTIS_GH_USER=atlantis-bot \ -e ATLANTIS_GH_TOKEN=$GH_TOKEN \ -e ATLANTIS_GH_WEBHOOK_SECRET=$WEBHOOK_SECRET \ -e ATLANTIS_REPO_ALLOWLIST="github.com/acme/*" \ -e ATLANTIS_ATLANTIS_URL=https://atlantis.example.com \ -e ATLANTIS_REPO_CONFIG=/etc/atlantis/repos.yaml \ ghcr.io/runatlantis/atlantis:v0.27 -
Webhook. In GitHub: Repo → Settings → Webhooks →
https://atlantis.example.com/events, content type JSON, secret =$WEBHOOK_SECRET, events:Issue comments,Pull requests,Pull request reviews,Pushes. -
Server-side config in
/etc/atlantis/repos.yaml:repos: - id: /github.com\/acme\/.*/ allowed_overrides: [workflow, apply_requirements] allow_custom_workflows: false apply_requirements: [approved, mergeable] workflows: default: plan: steps: - env: { name: TF_IN_AUTOMATION, value: "true" } - init: { extra_args: ["-upgrade=false"] } - plan: { extra_args: ["-lock=true"] } apply: steps: - apply terragrunt: plan: steps: - env: { name: TERRAGRUNT_TFPATH, value: "terraform" } - run: terragrunt run-all plan --terragrunt-non-interactive -out=$PLANFILE apply: steps: - run: terragrunt run-all apply --terragrunt-non-interactive $PLANFILEapply_requirements: [approved, mergeable]enforces that the PR has at least one approving review and no merge conflicts beforeatlantis applyworks. -
Per-repo config in
atlantis.yaml(in the repo root):version: 3 projects: - name: networking-prod dir: prod/networking workspace: default workflow: default autoplan: { when_modified: ["*.tf", "*.tfvars"], enabled: true } - name: app-prod dir: prod/app workspace: default workflow: default autoplan: { when_modified: ["*.tf", "../modules/**/*.tf"], enabled: true }when_modifiedpaths are relative to the project dir; the../modules/**/*.tfpattern triggers a re-plan when shared modules change. -
Policy checks. Atlantis can run
conftest(OPA) against the plan before apply is allowed. Add to the workflow:workflows: default: plan: steps: - init - plan - show - policy_check policy_check: steps: - policy_check: { extra_args: ["-p", "/etc/atlantis/policies"] }Policies live in
/etc/atlantis/policies/*.rego— common rules: no public S3 buckets, no security groups with0.0.0.0/0on port 22, tags required on every resource. -
PR workflow. Open PR → Atlantis posts plan → review (human + policy check) →
atlantis apply→ merge. The merge can be configured to auto-close the PR after apply. -
Unlock. If a PR is abandoned with the lock held, comment
atlantis unlockon either PR, or hit the/locksUI as an admin.
Common pitfalls
-auto-approvein the workflow. Don’t. The whole point is human review.- No
apply_requirements. Withoutapproved, anyone with comment rights can apply. Setapprovedand configure CODEOWNERS so the approval is from someone qualified. - Webhook secret unset. Atlantis accepts any webhook payload — including forged ones from an attacker who knows the URL. Always set
ATLANTIS_GH_WEBHOOK_SECRET. - State lock not released. A plan that hits a transient error sometimes leaves a state lock behind.
terraform force-unlockin the affected project’s directory clears it. - Concurrent Atlantis processes. Two Atlantis instances against the same repo race on locks. Run one instance (HA via active-passive with
atlantis-server-shutdown-grace-period).
We run Atlantis for clients with mid-to-large Terraform estates — typically when more than one team submits PRs against the same root modules. The webhook receiver, server-side repos.yaml, OPA policy library, lock-management runbook, and the on-call playbook for “PR stuck, plan won’t unlock” are all part of the operating model we ship as /en/services/managed-operations/. For larger fleets that need scheduled runs and drift detection, see also /en/knowledge-base/spacelift-overview-vs-atlantis/.