Skip to content

Atlantis — Terraform PR automation pattern

Run Terraform plan and apply through pull-request comments. Atlantis install, workflow customization, locking, and the policy-checks layer we add for clients.

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

  1. 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
  2. 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.

  3. 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 $PLANFILE

    apply_requirements: [approved, mergeable] enforces that the PR has at least one approving review and no merge conflicts before atlantis apply works.

  4. 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_modified paths are relative to the project dir; the ../modules/**/*.tf pattern triggers a re-plan when shared modules change.

  5. 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 with 0.0.0.0/0 on port 22, tags required on every resource.

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

  7. Unlock. If a PR is abandoned with the lock held, comment atlantis unlock on either PR, or hit the /locks UI as an admin.

Common pitfalls

  • -auto-approve in the workflow. Don’t. The whole point is human review.
  • No apply_requirements. Without approved, anyone with comment rights can apply. Set approved and 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-unlock in 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/.