Atlantis: Pull-Request Automation for Terraform

By Khimananda Oli | Last reviewed: August 2026

Managing infrastructure as code (IaC) becomes chaotic when multiple engineers modify shared resources without coordinated feedback loops. Atlantis: Pull-Request Automation for Terraform solves this by executing terraform plan and apply directly inside your Git provider, turning every infrastructure change into a transparent, reviewable event. Instead of granting developers direct cloud access or running plans locally with inconsistent states, you centralize execution in a controlled server environment that posts results back to the merge request. This approach aligns perfectly with the collaborative workflows detailed in our infrastructure as code with Terraform practical guide, ensuring safety scales alongside velocity.

How does Atlantis: Pull-Request Automation for Terraform actually work?

At its core, Atlantis acts as a specialized CI agent dedicated solely to Terraform operations. Unlike general-purpose CI pipelines where you must script every step, Atlantis understands Terraform semantics natively. When a developer opens a pull request modifying .tf files, your Git provider sends a webhook to the Atlantis server. Atlantis parses the payload, identifies which projects are affected based on directory structure or configuration, and clones the repository at that specific commit SHA.

The critical distinction here is execution context. Atlantis runs using server-injected credentials, meaning developers never need AWS keys or Azure tokens on their laptops. This aligns with zero-trust principles and simplifies onboarding significantly. After cloning, it initializes the backend, acquires a state lock to prevent concurrent modifications, and executes terraform plan. The resulting output—complete with resource additions, deletions, and modifications—is formatted and posted back to the pull request as a comment. Reviewers can then inspect the exact infrastructure impact before approving. Only after an approved review and an explicit atlantis apply comment does the actual deployment occur.

This workflow eliminates the "works on my machine" problem endemic to local Terraform execution. Every plan uses the same provider versions, backend configuration, and environment variables defined centrally. For teams managing complex environments, integrating this with Terraform state management and remote backends ensures that the Atlantis server is the single source of truth for all state interactions.

How do you configure Atlantis for multi-project repositories?

Most real-world infrastructure isn't a single flat directory. You likely have separate stacks for networking, databases, and applications, possibly across multiple regions. Atlantis handles this through its atlantis.yaml configuration file, which defines project boundaries and workflow customization. Without this file, Atlantis attempts autodiscovery, but explicit configuration is mandatory for production reliability.

Defining project directories and workspaces

Create an atlantis.yaml in your repository root to map directories to specific workflows. This tells Atlantis exactly what to plan when changes occur in specific paths:

version: 3
projects:
  - dir: infra/networking
    workspace: default
    autoplan:
      enabled: true
      when_modified: ["*.tf", "../modules/vpc/*.tf"]
  - dir: infra/app-production
    workspace: default
    terraform_version: 1.9.0
    autoplan:
      enabled: true
      when_modified: ["*.tf", "*.tfvars"]
workflows:
  custom-plan:
    plan:
      steps:
        - init
        - plan:
            extra_args: ["-var-file=prod.tfvars"]

The when_modified field is particularly powerful. It allows you to trigger plans not just when files in the immediate directory change, but also when shared modules are updated. This prevents the common failure mode where a module update breaks downstream consumers because they weren't re-planned automatically.

Customizing workflows and pre-hooks

You often need validation before planning. Atlantis supports custom workflow steps including shell commands. A common pattern I use involves running terragrunt or security scanners like checkov before the plan executes. This shifts compliance checks left, catching policy violations before reviewers spend time analyzing the plan output. Remember that these scripts run on the Atlantis server, so ensure necessary binaries are baked into your Atlantis container image.

What are the security best practices for Atlantis deployments?

Running Atlantis means giving a single application broad permissions to modify your infrastructure. Securing this component is non-negotiable. In my experience helping teams achieve SOC 2 compliance, Atlantis security controls frequently appear in audit evidence collection. Treat the Atlantis server as a Tier-0 asset equivalent to your CI/CD runners or secret management systems.

• Restrict webhook sources: Never expose Atlantis to the public internet without authentication. Use webhook signing secrets (GitHub/GitLab provide these) to verify payloads originate from your Git provider. Configure ingress controllers or load balancers to allow traffic only from known Git provider IP ranges if possible.
• Enforce branch protection: Atlantis should respect your Git provider's approval requirements. Configure require_approval and require_mergeable in your server-side config to prevent applies on unapproved or conflicting PRs. This creates a technical control enforcing your change management policy.
• Isolate credentials: Never pass cloud credentials via environment variables in docker-compose or Kubernetes manifests directly. Use IAM roles for service accounts (IRSA on EKS, Workload Identity on GKE/AKS) or integrate with HashiCorp Vault. If you must use static keys, store them in a secrets manager and inject them at runtime. Refer to Kubernetes secrets management done right for implementation patterns.
• Limit blast radius: Run separate Atlantis instances or configurations for staging and production. Use distinct cloud accounts or subscriptions per environment. This ensures a misconfigured staging plan cannot accidentally reference or modify production resources.
• Audit logging: Enable verbose logging and ship Atlantis logs to your centralized observability platform. Every plan and apply command, along with the user who triggered it via PR comment, should be traceable. This audit trail is essential for incident response and compliance verification.

How does Atlantis compare to Terraform Cloud and Spacelift?

Choosing between self-hosted Atlantis and managed platforms depends on budget, compliance requirements, and operational capacity. While Terraform Cloud (TFC) and Spacelift offer polished UIs and SaaS convenience, Atlantis remains the gold standard for teams requiring full data sovereignty and cost predictability at scale.

For Nepal-based organizations or companies with strict data residency requirements, Atlantis provides a path to enterprise-grade IaC automation without transferring sensitive infrastructure metadata to foreign SaaS providers. The trade-off is operational responsibility: you own the upgrades, scaling, and availability of the Atlantis server itself. However, given that Atlantis is a stateless Go binary backed by a simple database, this burden is manageable compared to maintaining a full Jenkins cluster.

How do you troubleshoot common Atlantis failures and performance issues?

Even well-configured Atlantis deployments encounter issues. Diagnosing them requires understanding the distinction between Atlantis errors and Terraform errors. When a plan fails, check the PR comment first—it usually contains the raw Terraform stderr. If the comment says "Error running plan" with no Terraform output, the issue is likely Atlantis infrastructure: git clone failures, network timeouts, or missing binaries.

A frequent pain point is long-running plans timing out. Atlantis has default timeouts for each step. For large monorepos or complex graphs, increase these in your workflow configuration. Also consider splitting projects; a single plan touching 500 resources will always be slow regardless of tooling. Parallelism helps, but only up to the point where cloud provider rate limits kick in. Implement exponential backoff in your provider configuration and use -parallelism flags judiciously.

State lock contention is another common failure. If two PRs modify overlapping resources, the second plan will fail waiting for the lock. Atlantis handles this gracefully by queuing or failing fast depending on configuration. Educate your team that this is a feature, not a bug—it prevents corruption. For persistent locking issues, verify your backend's lock table health and ensure no zombie processes exist from crashed Atlantis pods. Integrating monitoring via Prometheus metrics monitoring fundamentals allows you to alert on plan duration and lock wait times before developers complain.

Deploying Atlantis: Pull-Request Automation for Terraform Successfully

Adopting Atlantis: Pull-Request Automation for Terraform transforms infrastructure changes from risky manual operations into predictable, auditable engineering workflows. Start with a non-production environment to validate your webhook configuration and IAM roles before rolling out to production stacks. Invest time upfront in crafting a robust atlantis.yaml and baking necessary tooling into your container image; this foundation pays dividends as your repository grows. If you're evaluating whether Atlantis fits your specific compliance or architectural constraints, reach out to discuss your infrastructure automation strategy and get tailored guidance for your team's maturity level.