Terraform & Atlantis Integration Guide

What Is the Terraform & Atlantis Integration?

Atlantis is an open-source application that sits between your version control system (GitHub, GitLab, or Bitbucket) and Terraform, automating infrastructure-as-code workflows through pull requests. Rather than running Terraform commands manually on developer machines or in isolated CI/CD pipelines, Atlantis intercepts pull requests, runs Terraform plan operations, displays results as comments, and allows teams to approve and apply changes directly from the pull request interface.

This integration transforms how infrastructure teams manage Terraform—replacing ad-hoc command-line usage with a centralized, auditable, and collaborative workflow. It’s particularly valuable for organizations that want to enforce policy, maintain visibility, and prevent configuration drift without sacrificing developer velocity.

How the Integration Works

• Pull Request Interception: When a developer pushes Terraform code changes to a pull request, Atlantis receives a webhook notification from your Git provider and automatically triggers a Terraform plan operation against the target environment.
• Plan Display & Review: Atlantis runs the plan, parses the output, and posts a formatted comment on the pull request showing exactly what resources will be created, modified, or destroyed. This gives reviewers full visibility before any infrastructure changes occur.
• Approval & Apply Workflow: Team members can comment on the pull request with simple commands (e.g., “atlantis apply”) to approve and execute the Terraform apply. Atlantis enforces that the apply matches the previously reviewed plan, preventing drift between what was approved and what gets deployed.
• State Management & Locking: Atlantis manages Terraform state files and applies automatic locking to prevent concurrent operations on the same infrastructure, eliminating race conditions and state corruption.
• Policy Enforcement & Logging: The integration enables policy-as-code checks (via tools like Conftest or custom hooks), audit logging of all infrastructure changes, and role-based access controls tied to your Git repository permissions.

Key Features & Capabilities

• Automated Plan Comments on Pull Requests: Every Terraform configuration change automatically generates a detailed plan output as a pull request comment, eliminating the need for developers to run local plans and paste results manually.
• Centralized State Management: Atlantis stores and manages Terraform state files in a central location (local disk, S3, or other backends), reducing the risk of lost or corrupted state and enabling team-wide access without credential sharing.
• Pre-Apply Policy Checks: Integrate policy engines like Conftest or custom scripts to validate Terraform configurations against organizational standards before any infrastructure is provisioned, catching misconfigurations early.
• Multi-Environment & Multi-Workspace Support: Run Terraform plans and applies across multiple environments (dev, staging, production) and workspaces from a single pull request, with clear separation and approval controls for each.
• Audit Trail & Compliance Logging: Every plan, apply, and unlock operation is logged with timestamps, user information, and change details, providing a complete audit trail for compliance and troubleshooting.
• Automatic Locking & Concurrency Control: Atlantis prevents simultaneous Terraform operations on the same infrastructure by automatically locking state, eliminating the risk of conflicting changes and state corruption.

Setup Difficulty: Medium

Estimated Time: 30–60 minutes for a basic setup; more for advanced configurations.

Setting up Atlantis requires deploying it as a service (typically in Kubernetes, Docker, or on a VM), configuring webhooks in your Git provider, and setting up Terraform backend storage. You’ll need to:

• Deploy Atlantis (Docker container, Helm chart, or binary)
• Configure Git provider credentials and webhooks
• Set up Terraform backend storage (S3, Terraform Cloud, or local)
• Create an Atlantis configuration file (atlantis.yaml) in your repository to define how Terraform projects are organized
• Configure any policy checks or custom hooks if needed

No custom code is required for basic operation, but infrastructure knowledge (Kubernetes, Docker, or Linux) is helpful. Teams new to infrastructure-as-code workflows may need time to adjust to the pull request-driven model.

Alternatives & Workarounds

If Atlantis doesn’t meet your needs, consider these alternatives:

• Terraform Cloud / Terraform Enterprise: HashiCorp’s official managed service provides similar pull request integration, state management, and policy enforcement with a SaaS or self-hosted model. It’s more tightly integrated with Terraform but comes with licensing costs.
• Custom CI/CD Pipeline (GitHub Actions, GitLab CI, Jenkins): Build your own Terraform automation using native CI/CD tools, giving you full control over the workflow but requiring more maintenance and custom scripting.
• Spacelift or Env0: Third-party platforms offering Terraform orchestration with pull request workflows, policy enforcement, and additional features like cost estimation and drift detection.

Frequently Asked Questions

Does Atlantis work with Terraform Cloud or Terraform Enterprise?

Yes, Atlantis can integrate with Terraform Cloud or Enterprise by configuring it to use those services as a backend for state storage and remote operations. However, Terraform Cloud already includes native pull request integration, so using both together requires careful configuration to avoid redundancy. Most teams choose one or the other rather than both.

What Git providers does Atlantis support?

Atlantis supports GitHub, GitLab, Bitbucket, and Gitea. It integrates via webhooks, so any Git provider that supports webhooks can work with Atlantis, though the feature set may vary slightly between providers.

Can Atlantis enforce policies or prevent certain infrastructure changes?

Yes, Atlantis supports policy enforcement through custom hooks, Conftest integration, or external policy engines. You can define rules that block applies if configurations don’t meet organizational standards, such as requiring specific tags, limiting resource types, or enforcing encryption settings.

How does Atlantis handle state file security and access control?

Atlantis manages state files in a centralized backend (S3, GCS, Azure Storage, or local disk) and controls access through Git repository permissions. Team members can only run plans and applies if they have write access to the repository. For sensitive state data, use encrypted backends and restrict Atlantis service account permissions to the minimum required.

Disclaimer

Integration features and capabilities may change as both Terraform and Atlantis evolve. This guide reflects current best practices as of publication. Always verify current functionality and compatibility on the official Atlantis documentation and Terraform provider documentation before implementing in production.