Atlantis

Atlantis is an open-source tool that brings Terraform workflows into GitHub pull requests. Instead of running terraform plan and terraform apply from a developer’s laptop, Atlantis runs them on a server and posts the output back to the PR as comments. This gives infrastructure changes the same review, approval, and audit trail as application code.

PR-Driven Workflow

The standard Atlantis loop looks like this:

1. A developer opens a PR that changes Terraform configuration.
2. A reviewer comments atlantis plan on the PR.
3. Atlantis checks out the branch, runs terraform plan, and posts the output as a PR comment.
4. The team reviews the plan.
5. A reviewer comments atlantis apply.
6. Atlantis runs terraform apply and posts the apply output as a comment.
7. The PR is merged.

Because the plan is visible in the PR, reviewers can see exactly what will be created, changed, or destroyed before approving. This is the infrastructure equivalent of a code diff.

Project Locking

Terraform state is a shared resource. If two PRs are opened against the same project and both run apply, the second plan may be based on stale state and can corrupt infrastructure. Atlantis prevents this with project-level locks.

When atlantis plan runs on a PR, Atlantis locks the project for that PR. If another PR tries to plan the same project, Atlantis comments that the project is locked and lists the blocking PR. The lock is released when the first PR is merged or closed. This serializes writes while still allowing parallel planning.

The 2017 project demo shows this exact scenario: a second PR is blocked until the first PR is applied and merged Atlantis Walkthrough.

Approval Gating

Atlantis can require one or more GitHub approvals before atlantis apply is allowed. This adds a manual gate to destructive changes and aligns with the principle that infrastructure modifications should be reviewed by a second person.

Centralized Credentials

Because Terraform runs on the Atlantis server rather than on individual laptops, developers do not need personal cloud credentials. The Atlantis server holds the credentials for AWS, Azure, GCP, or other providers. This reduces credential sprawl and makes it easier to enforce least-privilege access: only the Atlantis service account needs broad permissions.

Configuration

Atlantis is configured with a server-side config file (or flags) and a per-repository atlantis.yaml. The repository config can define:

• Which directories are Terraform projects
• Which workflows to use (plan, apply, custom scripts)
• Execution order and dependencies between projects
• Required approval counts

Relationship to GitOps

Atlantis predates the popularization of “GitOps” but implements one of its core ideas: the desired state lives in Git, and changes flow through reviewed PRs. Unlike Kubernetes GitOps tools such as Argo CD or Flux, Atlantis does not continuously reconcile state. It is event-driven: it acts when a reviewer asks it to plan or apply. This makes it a good fit for Terraform workflows where continuous reconciliation is neither needed nor desirable.

Security Considerations

• Authenticate Atlantis to GitHub using a GitHub App or fine-grained PAT rather than a long-lived classic PAT
• Run Atlantis in a hardened environment with least-privilege cloud credentials
• Require approvals before apply
• Do not expose the Atlantis webhook endpoint to the public internet without authentication
• Keep Terraform state in an encrypted remote backend, never in the repository

See Also

• Terraform — the infrastructure-as-code tool that Atlantis orchestrates
• Atlantis Walkthrough — Source: original project demo
• GitOps Security — repository hardening, PAT hygiene, and PR workflow security
• DevSecOps Fundamentals — IaC validation and policy enforcement in the pipeline
• Shift Left Security — finding misconfigurations before they reach Terraform apply
• Tooling Index — DevOps and IaC tooling overview
• Kubernetes Disaster Recovery — Infrastructure-as-Code as the foundation of cluster recovery