Atlantis is an open-source Terraform automation tool that streamlines infrastructure changes through pull request workflows. It automates Terraform plan and apply operations while providing centralized execution, state management, and governance controls. As a Cloud Native Computing Foundation sandbox project with Apache 2.0 licensing, Atlantis has established itself as the leading self-hosted alternative to commercial Terraform automation platforms. Its primary value proposition lies in enabling organizations to implement collaborative infrastructure-as-code workflows while maintaining complete control over their deployment environment and sensitive credentials.
The tool addresses core challenges in collaborative infrastructure management by preventing state file corruption, eliminating race conditions between concurrent changes, and providing comprehensive audit trails of all infrastructure modifications. It removes the risks associated with executing Terraform commands on individual developer machines while enabling broader team participation in infrastructure changes through familiar pull request workflows. Platform engineering teams use it to implement standardized processes for infrastructure changes while maintaining security and compliance requirements.
What Atlantis Is and Why It Exists
Terraform is a standard in infrastructure as code, but managing it at scale can be cumbersome. As a result, the adoption of Terraform Automation and COllaboration Software, TACOS, is rising. One of these tools is Atlantis.
Atlantis is an automation tool that enhances the PR workflows for Terraform projects. It is used to reduce the complexity of collaboration and governance for your Terraform workflow. The tool is open-source and does not offer any SaaS, so you will have to install and configure it yourself.
With Atlantis, you get support for multiple VCS providers such as GitHub, Bitbucket, GitLab, and Azure DevOps, and you can leverage both Terraform and Terragrunt workflows. Atlantis runs as a golang binary or Docker image and you can deploy it on VMs, Kubernetes, Fargate, etc.
Atlantis is free and open source under the Apache 2.0 license. It can be self-hosted without any licensing cost, making it a popular choice for teams automating Terraform pull request workflows. Some companies offer paid support or hosted versions, but the core tool itself is free.
The main benefit of using Atlantis with Terraform is that it enables automated Terraform operations via pull requests, enforcing infrastructure-as-code workflows through Git. When a PR is opened, Atlantis runs plan, adds results as a comment, and applies changes only after review and approval, reducing risk and improving collaboration.
How Atlantis Works in a Pull Request Lifecycle
Atlantis offers a structured approach that ensures infrastructure changes are made in a controlled, transparent, and collaborative manner, integrating seamlessly with the existing pull request workflow used by development teams.
Initialization is the first step. You need to install and configure Atlantis in your environment. It can be configured either on-premise, or in a cloud environment. There are various ways to install it. Once running, Atlantis watches the configured repositories for pull requests.
Key steps of how Atlantis works:
- Initialization
- You need to install and configure Atlantis in your environment. It can be configured either on-premise, or in a cloud environment. There are various ways to install it
- Detection
- When a developer opens a pull request containing Terraform changes, Atlantis detects the change through webhook integration with the VCS provider.
- Plan execution
- A developer comments atlantis plan on a PR and Atlantis runs the plan, posts the output as a comment, and waits for atlantis apply to execute changes.
- Review and governance
- The plan output is visible to reviewers as a comment on the PR. If the run is discarded, the process stops at this point.
- Apply execution
- If the review ends with an approval, you can run atlantis apply via a PR comment.
- Atlantis will run terraform apply behind the scenes and comment the output on the PR.
- Merge
- If everything is successful, you can merge the pull request and delete the feature/hotfix branch.
Instead of running Terraform locally or configuring complex CI/CD pipelines, developers comment atlantis plan on a PR and Atlantis runs the plan, posts the output as a comment, and waits for atlantis apply to execute changes.
Centralized Execution and State Safety
Collaborative Terraform usage without guardrails creates operational risk. Running Terraform on individual developer machines exposes state files, credentials, and provider configurations to the local environment. Concurrent applies from different engineers can corrupt state files and create race conditions.
Atlantis centralizes execution in a single controlled environment. All plan and apply operations run inside the Atlantis instance, not on laptops. This prevents state file corruption, eliminates race conditions between concurrent changes, and provides comprehensive audit trails of all infrastructure modifications.
The tool removes the risks associated with executing Terraform commands on individual developer machines while enabling broader team participation in infrastructure changes through familiar pull request workflows. It serves platform engineering teams seeking to implement standardized processes for infrastructure changes while maintaining security and compliance requirements.
The value proposition is control. Organizations maintain complete control over their deployment environment and sensitive credentials. There is no SaaS dependency for the core automation. The Apache 2.0 license permits self-hosting without licensing cost.
Deployment Options and Platform Support
Atlantis runs as a golang binary or Docker image and you can deploy it on VMs, Kubernetes, Fargate, etc.
Deployment flexibility is important for platform engineering teams with different operational constraints.
| Deployment Target | Typical Use Case | Notes |
|---|---|---|
| Virtual Machine | On-premise or private cloud control | Direct binary install, persistent volume for state |
| Docker Container | Quick start and portability | Official image, easy CI integration |
| Kubernetes | Scaled self-hosted automation | StatefulSet for webhook and worker pods |
| AWS Fargate | Serverless container execution | No VM management, cloud native |
| Cloud VM | Hybrid environments | Full control over network and secrets |
VCS integration is broad.
| VCS Provider | Supported Features |
|---|---|
| GitHub | Webhook, PR comments, status checks |
| Bitbucket | Webhook, PR comments, approvals |
| GitLab | Merge request integration, comments |
| Azure DevOps | Pull request automation, comments |
Atlantis also supports both Terraform and Terragrunt workflows.
Atlantis with Terragrunt
HashiCorp Terraform is a declarative tool for infrastructure as code that emerged in 2014. You can run it on your local system, integrated as part of your CI/CD pipelines, on your build servers, bundled in some IaC platforms, or in other ways. Smooth workflows for collaboration on Terraform configurations are crucial for successful IaC.
When you write Terraform configurations at scale for large cloud infrastructures, Terraform code including provider definitions and state backend configurations will repeat throughout all your configurations. Keeping things like provider versions up to date across all Terraform configurations can be tedious.
A whole ecosystem of tools has grown around Terraform to help you run it at scale. In this post, focus is Atlantis and Terragrunt — specifically, how to run Atlantis with Terragrunt.
Note: Atlantis and Terragrunt also work well with OpenTofu.
Terragrunt complements Terraform by reducing duplication and standardizing backend configuration. Atlantis detects Terragrunt files and executes terragrunt plan and apply instead of raw terraform commands when configured.
A sample Terraform module used for testing Atlantis with Terragrunt generates a random integer within a specified range provided as input to the module.
terraform
terraform {
required_providers {
random = {
source = "hashicorp/random"
version = "~> 3.7"
}
}
}
variable "min" {
type = number
default = 1
}
variable "max" {
type = number
default = 100
}
resource "random_integer" "default" {
min = var.min
max = var.max
}
output "result" {
value = random_integer.default.result
}
This Terraform module will be provisioned in the dev and prod environments. Note that when working with Terragrunt, it is preferable to work with immutable module versions rather than directly with local modules, as we will do in this example. This setup is for illustrative purposes only.
We will use Terragrunt to generate the Terraform state backend configuration for each environment. Terragrunt files can define common remote state settings, provider versions, and input overrides per environment, while Atlantis orchestrates the plan and apply across those environments through PR comments.
Benefits, Use Cases, and Governance Outcomes
The main focus of Atlantis is to extend Terraform’s capabilities when working in a team. It ensures changes are collaborative, auditable, and consistent.
Here are examples of Atlantis use cases:
- Enhanced collaboration: Atlantis fosters better collaboration among team members by integrating with version control systems. It provides a centralized platform for code review and feedback, ensuring a structured and efficient workflow.
- Pull request management: Atlantis excels in managing pull requests within your VCS. It enables the automatic triggering of Terraform commands within the context of pull requests, allowing reviewers to make thorough decisions when there are infrastructure changes.
- Automation and consistency: It automates Terraform workflows and maintains consistency across different environments. Terraform commands are automated, and this reduces the need for manual intervention and minimizes human error.
- Integration with CI/CD systems: Atlantis can be seamlessly integrated into CI/CD systems, enabling IaC CI/CD.
Governance controls are built into the workflow. Approvals can be enforced before apply. Required reviewers, policy checks, and custom workflows can be layered on top of Atlantis. Because all actions are performed via PR comments, there is a complete audit trail of who requested a plan, who approved an apply, and what Terraform output was produced.
The tool is a better, more flexible CI/CD for Terraform, offering maximum security without sacrificing functionality.
Practical Configuration Considerations
Atlantis is open-source and does not offer any SaaS, so you will have to install and configure it yourself. Configuration typically involves defining allowed repositories, webhook secrets, Terraform CLI version, working directory detection, and access tokens for VCS providers.
State management is handled centrally. Atlantis can lock state, serialize applies, and prevent concurrent runs on the same workspace. This eliminates race conditions that occur when multiple engineers run apply locally.
For teams using Terragrunt, the working directory detection can be set to prefer terragrunt.hcl. The plan and apply commands are automatically translated. State backend configuration is generated per environment via Terragrunt, reducing repetition across dev and prod.
Security posture improves because credentials never leave the Atlantis execution environment. Developers interact only through PR comments, and all Terraform execution happens in a controlled, audited environment.
Conclusion
Atlantis provides a mature, self-hosted automation layer for Terraform that replaces ad-hoc local execution with a pull request driven workflow. By automating plan and apply through PR comments, it enforces collaborative review, centralized execution, and auditable governance without requiring commercial licensing.
The combination of Apache 2.0 licensing, CNCF sandbox status, support for multiple VCS providers, and compatibility with both Terraform and Terragrunt makes it a strategic choice for platform engineering teams that need control over their deployment environment and sensitive credentials. The tool prevents state corruption, eliminates race conditions, and creates a transparent audit trail for every infrastructure change.
For organizations already invested in Git-based development workflows, Atlantis reduces the complexity of collaboration and governance for Terraform workflows while preserving the flexibility to deploy on VMs, Kubernetes, Fargate, or on-premise infrastructure. When paired with Terragrunt for DRY configuration and backend management, the solution scales to large cloud infrastructures where provider versions and state backends would otherwise repeat across repositories.
The operational model is simple: developers open a PR, comment atlantis plan, review the posted output, and after approval comment atlantis apply. Atlantis runs the commands centrally, posts results back to the PR, and maintains full control over credentials and state. This is the core of Terraform Automation and COllaboration Software in practice.