Atlantis is a tool that bridges the gap between GitOps and Terraform, enabling infrastructure changes to be managed via pull requests.
Here’s how it works in action. Imagine you have a Terraform configuration for deploying a new EC2 instance. You make a change to main.tf, perhaps increasing the instance size or adding a new tag. You commit this change and push it to a feature branch.
# main.tf
resource "aws_instance" "example" {
ami = "ami-0abcdef1234567890"
instance_type = "t3.micro" # Changed from t3.nano
tags = {
Name = "MyExampleInstance"
Environment = "Development"
}
}
You then open a pull request against your main branch. Atlantis, configured to watch this repository and branch, detects the new pull request. It automatically runs terraform plan for the changes in the PR and posts the output directly into the pull request comments.
Terraform Plan:
Terraform used the selected provider to generate the plan. Terraform can automatically adapt to new Provider versions.
Terraform will perform the following actions:
# aws_instance.example will be updated in-place
~ resource "aws_instance" "example" {
id = "i-0123456789abcdef0"
~ instance_type = "t3.nano" -> "t3.micro"
tags = {
"Environment" = "Development"
"Name" = "MyExampleInstance"
}
# (1 unchanged attribute hidden)
# (1 unchanged resource hidden)
}
Plan: 0 to add, 1 to change, 0 to destroy.
This allows your team to review the proposed infrastructure changes directly within the familiar context of a pull request. Before merging, someone can comment on the PR with a command like atlantis apply. Atlantis parses this comment, executes terraform apply on the modified Terraform configuration, and again posts the output back into the PR, showing the results of the apply.
The core problem Atlantis solves is the lack of visibility and control in traditional infrastructure-as-code workflows. Without it, developers might run terraform apply locally, leading to drift between local states and the actual deployed infrastructure, or rely on manual, error-prone deployment processes. Atlantis brings a structured, auditable, and collaborative approach to infrastructure management. It enforces a review process, ensuring that no infrastructure changes are deployed without explicit approval and that the entire history of changes is logged in your Git repository.
Atlantis operates by watching Git events (like pull request creation and updates). When a relevant event occurs, it clones the repository, checks out the specific branch associated with the pull request, and then executes the requested Terraform commands (plan, apply, destroy) within that context. It uses a webhook to receive notifications from your Git provider (GitHub, GitLab, Bitbucket, etc.) and communicates its results back to the pull request via the Git provider’s API.
The exact levers you control are primarily within Atlantis’s configuration file (config.yaml) and your Terraform code. In config.yaml, you define which repositories Atlantis should monitor, which Git branches trigger actions (e.g., main, master), the Terraform working directory, and any custom Terraform environment variables or flags. For example, you might specify:
# config.yaml
terraform:
enabled: true
workflow- கருவி: terraform
# ... other terraform settings
parallel-plan-workflows:
- name: terraform
plan:
steps:
- init
- plan:
extra-args: ["-var-file=production.tfvars"]
parallel-apply-workflows:
- name: terraform
apply:
steps:
- apply:
extra-args: ["-auto-approve"]
This configuration tells Atlantis to use Terraform, to execute terraform init followed by terraform plan (passing an extra argument -var-file=production.tfvars), and then terraform apply (with -auto-approve).
The one thing most people don’t know is that Atlantis can be configured to run multiple Terraform projects within a single pull request. If your repository contains distinct Terraform modules or environments (e.g., a modules/vpc directory and an environments/staging directory), Atlantis can be set up to plan and apply them independently or in sequence based on your config.yaml. This is achieved through its autoplanner feature and by defining multiple projects within your atlantis.yaml file located at the root of your repository or within specific project directories. This allows for granular control over how changes to different parts of your infrastructure are handled.
The next step in mastering Atlantis is exploring its integration with CI/CD pipelines for more complex validation and testing before an apply.