Atlantis for Terraform: What It Is, How It Works, Pros & Cons

What is Atlantis?

Atlantis is an open-source tool that automates operations within Terraform pull requests. It posts terraform plan outputs as comments for review. Approved changes can be applied directly via a PR command. This approach makes infrastructure updates visible and traceable in your version control system. Teams see planned effects quickly, enabling faster, more confident infrastructure deployments. The system acts as a direct interface for Terraform actions and Terraform workflows.

Key Features of Atlantis

Centralized Collaboration & Visibility: Atlantis posts terraform plan outputs directly into pull requests. This means everyone on the team can see and discuss proposed infrastructure changes in one place, before they are applied. There's no need to guess what a change will do; it's laid out in the PR.

Enforced Workflow & Consistency: Atlantis standardizes the process of reviewing and applying Terraform configurations. By requiring changes to go through a pull request and an Atlantis workflow (plan, approve, apply), it ensures that all modifications follow the same procedure, reducing human error and "works on my machine" issues.

Increased Developer Experience: Atlantis automates the manual steps of checking out a branch, running terraform plan, sharing the output, and then running terraform apply. Developers can trigger these actions with simple PR comments, saving significant time.

Improved Control:

• Review Gate: Changes are planned and require review (and often explicit approval via a command like atlantis apply) before being executed.
• Impact Assessment: The plan output shows exactly what will be created, modified, or destroyed.
• Locking: Atlantis typically locks Terraform state files when a plan is run for a pull request, preventing conflicting changes from other PRs being applied simultaneously.

Enhanced Auditability: All actions—planning, approvals, applications—are logged within the pull request history. This creates a clear audit trail, showing who proposed what change, who reviewed it, and when it was applied.

Reduced Dependency on Local Setups for Applies: Since Atlantis runs terraform apply from a central, controlled environment, individual developers might not need to have cloud credentials or specific Terraform binary versions configured locally to apply changes, which can simplify setup.

Streamlined Onboarding: New team members can more easily get up to speed with infrastructure changes, as the process is clearly defined and visible within the familiar pull request interface.

The Common Atlantis Workflow

A common Atlantis workflow revolves around managing Terraform changes through pull requests (PRs) in a version control system (VCS) like GitHub, GitLab, Azure DevOps, or Bitbucket. Here's a typical sequence:

Developer Makes Changes: A developer creates a new branch, modifies Terraform configuration files (.tf files), and commits these changes.

Open a Pull Request: The developer pushes the branch and opens a pull request (or merge request) to merge their changes into the main branch (e.g., main, master).

Automatic Plan: Atlantis, which is configured to monitor the repository, automatically detects the Terraform changes in the new PR. It then runs terraform plan for each Terraform project or directory affected by the changes.

Plan Output as a Comment: Atlantis posts the output of the terraform plan command as a comment directly on the pull request. This allows the developer and their team to see exactly what infrastructure changes (creations, modifications, deletions) will occur if these Terraform configurations are applied.

Review and Discussion: Team members review the proposed code changes and the terraform plan output within the pull request. They can discuss the changes, ask questions, or request modifications using PR comments.

Iterate (if necessary): If changes are needed, the developer makes further commits to their branch. Each new push to the branch will typically trigger Atlantis to re-run terraform plan and update the comment with the new plan output.

Approval and Apply Command: Once the plan looks correct and the PR has been approved by the team (according to their review processes), a user with appropriate permissions comments on the PR with a specific command, usually atlantis apply.

In some configurations, atlantis apply might require specifying the project/directory if the PR affects multiple Terraform projects: atlantis apply -d <directory_name> or atlantis apply -p <project_name>.

Execute Apply: Atlantis receives this command and executes terraform apply, using the plan file that was generated and approved earlier. This ensures that only the reviewed changes are applied.

Apply Output as a Comment: Atlantis posts the output of the terraform apply command as another comment on the pull request, showing the results of the infrastructure update.

Merge Pull Request: After the apply is successful and the infrastructure is updated, the pull request can be merged into the main branch.

Unlock State (Automatic): Atlantis typically manages state locking, ensuring that only one operation occurs at a time for a given Terraform state. After the apply, it automatically unlocks the state.

Pros and Cons of Using Atlantis

Pros of Using Atlantis:

GitOps for Infrastructure: Atlantis deeply integrates with your version control system (GitHub, GitLab, Bitbucket, Azure DevOps). This allows teams to manage infrastructure changes using familiar pull request (PR) workflows, promoting collaboration, code review for infrastructure, and a clear audit trail.

Automation of plan and apply: It automatically runs terraform plan when a PR is opened or updated and posts the output as a comment. Approved plans can then be applied with a simple comment like atlantis apply. This reduces manual effort and speeds up the deployment cycle.

Consistency and Standardization: Ensures that Terraform commands are run in a consistent environment and manner, reducing the "works on my machine" problem and standardizing how infrastructure changes are reviewed and implemented.

Improved Security (in some aspects):

Reduced Local Credentials: Developers may not need direct cloud provider credentials on their local machines to apply changes, as Atlantis handles the apply step from its secure environment.

Controlled Execution: Changes are reviewed and explicitly approved before being applied.

State Locking: Atlantis automatically locks Terraform states during plan and apply operations for a given project/workspace. This prevents concurrent modifications from different PRs, which could otherwise lead to state corruption or unexpected outcomes.

Open Source: Being open-source, it's free to use and can be customized. Self-hosting gives organizations complete control over the Atlantis instance, its configuration, and where credentials are stored.

Enhanced Collaboration & Visibility: The entire process of planning, reviewing, and applying infrastructure changes happens within the PR, making it visible to the whole team.

Cons of Using Atlantis:

Self-Hosting and Maintenance Overhead: As a self-hosted tool, your team is responsible for deploying, maintaining, securing, and upgrading the Atlantis server. This requires operational effort.

Single Point of Failure (Potentially): Unless configured for high availability (which adds complexity), the Atlantis server itself can become a single point of failure. If it's down, the automated Terraform workflow is stalled.

Concurrency: By default, Atlantis processes PRs and their associated plan/apply operations sequentially for a given instance. While it can handle many repositories, very high volumes of concurrent PRs across many teams might lead to queues and delays without scaling strategies (e.g., multiple Atlantis instances with sharding logic).

Limited Native Integrations beyond VCS: Compared to commercial CI/CD platforms or dedicated Terraform automation solutions (like Terraform Cloud, Scalr, Env0, Spacelift), Atlantis has fewer built-in integrations with external tools for things like advanced policy checking (e.g., OPA, Checkov without custom scripting), cost estimation, or advanced security scanning. While some can be added with custom workflows, it requires more setup.

Basic UI/UX: Atlantis primarily operates via PR comments and has a very basic web UI for viewing logs and locks. It lacks the sophisticated dashboards and reporting features of some commercial alternatives.

Workflow Rigidity: While customizable to an extent, the core workflow is tied to pull requests. Complex scenarios or workflows not fitting this model might be harder to implement.

No Built-in Advanced RBAC: Role-based access control is primarily managed through VCS repository permissions and Atlantis's own configuration for who can apply. More granular RBAC within Atlantis is limited.

How Scalr Improves the Atlantis Workflow

While Atlantis is a great tool, it does lack some of the robust features that organizations need at scalr. Scalr aims to provide a more robust and feature-rich experience for Terraform automation, addressing many of the inherent challenges of a self-managed tool like Atlantis while building upon its foundational GitOps principles. Here's how Scalr helps with the previously discussed pros and cons:

Addressing the Cons of Atlantis:

Self-Hosting and Maintenance Overhead: Being a SaaS (Software-as-a-Service) platform, Scalr eliminates the need for users to deploy, maintain, secure, and upgrade their own automation servers. Scalr manages the underlying infrastructure, freeing up significant operational resources. Scalr offers self-hosted agents for organizations that need to execute runs within their own network.

Single Point of Failure: As a SaaS provider, Scalr is responsible for the high availability and reliability of its platform. Users benefit from an architecture designed for uptime, without needing to implement HA themselves.

Scalability Concerns (Concurrency, Resource Intensity): Scalr is designed to handle Terraform operations at scale, managing concurrent runs and resource allocation more dynamically than a typical single Atlantis instance might without significant custom configuration.

Limited Native Integrations beyond VCS: This is a key area where Scalr offers more. It provides built-in integrations for Open Policy Agent (OPA) for policy-as-code, security scanning tools (like Checkov), and often features like cost estimation. The VCS integration also enables the capability of creating a private module registry. This allows for more sophisticated governance and control directly within the platform.

Basic UI/UX: Scalr offers a dedicated web interface that provides a richer user experience than Atlantis's PR comment-driven interaction and basic UI. This includes dashboards, environment management, RBAC configuration, and clearer visibility into workspaces and runs.

Security of the Atlantis Instance (Server-Side): Scalr takes on the responsibility for the security of its platform. It provides features for secure credential management and integrates with your VCS and cloud providers through secure mechanisms. Access the Scalr trust center at trust.scalr.io.

Workflow Rigidity: Scalr often provides more flexibility with its hierarchical model (e.g., organizations, environments, workspaces), custom hooks, and the ability to define more complex workflows, including pre- and post-apply logic, beyond what a basic Atlantis setup might offer.

No Built-in Advanced RBAC: Scalr offers robust Role-Based Access Control (RBAC), allowing organizations to define granular permissions for users and teams across different environments and workspaces, which is crucial for larger organizations and enterprise governance.

Enhancing or Modifying the Pros of Atlantis:

GitOps for Infrastructure: Scalr fully embraces and builds upon the GitOps model. It integrates with your VCS to automate plan and apply stages based on pull request events, similar to Atlantis, but adds layers of governance and control.

Automation of plan and apply: Scalr Provides this core automation but enhances it with features like OPA policy checks between plan and apply, contextual RBAC, and better visibility through its UI.

Consistency and Standardization: Scalr enforces consistency not just in execution but also in governance, through shareable module registries, standardized environments, and enforced policies.

Improved Security (Reduced Local Credentials, Controlled Execution): Scalr strengthens this by providing a centralized and secure way to manage cloud credentials, enforcing OPA policies for security best practices, and using RBAC to control who can approve and apply changes.

State Locking & Remote State Management: Scalr manages Terraform state remotely and handles state locking seamlessly as part of its service, ensuring safe concurrent operations. Scalr also supports the ability to store state in your own cloud bucket.

Open Source and Self-Hosted (This is a key difference):

• Atlantis: Is open-source and typically self-hosted, offering maximum control and no vendor licensing fees.
• Scalr: Is a commercial product (SaaS primarily, with a self-hosted option). This means there's a cost, but it comes with support, managed services, and advanced enterprise features out-of-the-box. Scalr's pricing model is usage-based; you only pay for runs that you use…nothing else.

Enhanced Collaboration & Visibility: While Atlantis provides collaboration via PR comments, Scalr enhances this with a centralized dashboard showing all active runs, historical data, policy compliance, and environment statuses, offering a broader view for teams and management.

Scalr takes the core GitOps automation concept popularized by tools like Atlantis and builds a managed, enterprise-grade platform around it, focusing on governance, security, scalability, and ease of use for organizations managing Terraform at scale.

The Atlantis Workflow in Scalr

1. Enable the feature for the VCS provider

In addition to existing VCS features, such as “Trigger runs for draft pull requests” and “Send the plan summary back to pull request comments”, we added two more features: “Allow triggering plan-only runs from the PR comments” and “Allow triggering apply runs from the PR comments”. Once admins enable it, users can trigger runs from the PR comments.

2. Execute a Run From a Pull Request

Once VCS admins enable the end-users to trigger plans and applies from the PR, users can add the following comments, which will trigger runs in Scalr:

• /scalr plan - triggers plan-only Terraform runs in all workspaces with the VCS-driven dry runs enabled that are affected by the proposed changes.
• /scalr plan -force - also triggers plan-only Terraform runs, but it ignores the Enable VCS-driven dry runs workspace setting. This is very helpful when users want to ensure changes without changing the default workspace settings.
• /scalr apply - triggers apply Terraform runs in all workspaces affected by the PR. ‍
• /scalr apply -workspace-id=ws-12345678 - allows you to limit the workspaces you want to run a Terraform apply first (e.g. in the pre-production workspace).
• /scalr approve - approves a Terraform run waiting on an approval before the apply.

3. Scalr Integration

Behind the scenes, Scalr picks up the comment event and initiates the Opentofu/Terraform workflow. Before running the operation, you can configure the pipelines to check for specific conditions like approvals or preconditions.

4. Output and Feedback

Once the plan is completed, the result (success/failure, resource changes, etc.) is automatically posted as a comment in the pull request thread, keeping your Terraform code review and infrastructure workflows fully integrated.

5. Control Runs Through OPA (Optional)

Want to limit which Scalr environments can have runs executed in workspaces from pull request comments? Scalr’s integration with Open Policy Agent (OPA) can prevent various run sources, including PR comments. Every run that is executed in Scalr provides a source for the Terraform run input in OPA:

{
  "tfrun": {
    "workspace": {
   ....
   ...
   ..
    },
    "environment": {
      "id": "env-v0oj55tcci963d86q",
      "name": "Atlantis"
    },
    "vcs": {
      "repository_id": "repo/pr-driven",
      "branch": "dev",
      "commit": {
        "sha": "204b4ac780eea11c2fe9a639fc873acd23627daa",
        "message": "Update main.tf",
        "author": {
          "name": "user",
          "email": "[email protected]",
          "username": "user",
          "teams": null
        }
      },
      "pull_request": null
    },
    "cost_estimate": {
      "prior_monthly_cost": 0.0,
      "proposed_monthly_cost": 0.0,
      "delta_monthly_cost": 0.0
    },
    "source": "comment-github",
    "message": "Update main.tf",
    "is_destroy": false
   … 
   ..
   .

As seen above, an OPA policy check can be created to deny any run with the "source": "comment-github" or deny any run that isn’t "source": "comment-github". A use case for this is to allow PR-driven runs from lab and development environments, but maybe not production.

Learn more on OPA here.

6. Other Features Scalr Implemented for the Atlantis workflow

Avoid State Update by Unmerged PRs

Want to ensure that Terraform state modifications are only applied from the main workspace branch or a verified PR, preventing accidental overwrites or conflicts caused by unmerged changes? 

Scalr safeguards your Terraform state from unintended modifications with branch awareness. Scalr displays warnings when changes are attempted from branches with unmerged pull requests, and automatically prevents auto-apply operations when the state-generating branch differs from your run's configuration branch. This ensures state modifications only occur from your main workspace branch or properly verified pull requests, preventing accidental overwrites and conflicts.

Prevent an Apply from a PR that Cannot be Merged

If you are using the apply before merge workflow, you want to make sure that the /scalr apply command can only be executed after a PR is approved and passes branch protection checks, so you can enforce compliance and prevent unauthorized Terraform changes. This can be done by checking the merge_error attribute in the run input. See more on this here.

Automatic Base Branch Merge Before Run Execution

VCS-driven workspaces can automatically merge the base branch into the head branch before triggering a run. This ensures that runs are always executed against the latest code in the base branch, providing more accurate and reliable results. This helps a common pain point where runs could be executed against outdated head branches, potentially leading to false-positive results or failed applies after merging.

Get Started Today

Ready to streamline your Terraform development process? Head over to our documentation to learn how to set up PR-Comment-Based Opentofu/Terraform Runs in Scalr. It’s quick to configure and can dramatically improve how you manage Terraform configuration changes.

As always, we value your feedback. Let us know how this feature impacts your Terraform projects and development process, and share your thoughts on future enhancements!

Sign up for the Scalr free tier and see how easy it is to reproduce the Atlantis workflow in Scalr.

‍