DOCSEARCHbyAlgolia
Submit Docs

Atlantis: Terraform Automation for Pull Requests

website·Indexed Apr 12, 2026

https://www.runatlantis.io/

Atlantis automates Terraform workflows by running plans on pull requests to catch errors before applying changes. It supports self-hosted deployments on Kubernetes, VMs, or Fargate across GitHub, GitLab, Bitbucket, Azure DevOps, and Gitea. The tool provides audit logs, credential security, approval workflows, and directory locking for infrastructure changes in production environments.

Tokens
4.6K
Snippets
14
Records
50
Agent score
50%

What's inside Atlantis

  1. Supported Repository Structures

    Atlantis supports any Terraform repository structure: (1) Single project at repo root with main.tf at the root, (2) Multiple project folders where each subdirectory contains its own Terraform files, (3) Modules where shared modules are in a modules/ directory. For modules, create an atlantis.yaml to enable automatic planning of projects when modules are modified.

  2. Metrics Overview

    Atlantis exposes operational metrics for errors, successes, and latencies. Currently, both Statsd and Prometheus are supported. Metrics are accessible at the /metrics endpoint and are configured through the Server Side Config.

  3. Custom Workflows Configuration Structure

    Custom workflows in Atlantis override default commands via server-side repos.yaml or repo-level atlantis.yaml files. Define custom plan, init, and apply stages using extra_args and environment variables. When multiple projects share the same directory and workspace, a unique name key is required to differentiate them.

  4. Production Installation Overview

    This guide covers installing a production-ready Atlantis instance in 6 steps: (1) Verify Terraform requirements, (2) Generate Git host access credentials for GitHub/GitLab/Gitea/Bitbucket/Azure DevOps, (3) Create a webhook secret for validating webhooks, (4) Deploy Atlantis to your infrastructure, (5) Configure webhooks on your Git host to respond to pull requests, (6) Configure provider credentials for running Terraform commands. For testing first, see Test Drive or Testing Locally guides.

  5. Post Workflow Hooks Overview

    Post workflow hooks run scripts after default or custom workflows complete. They differ from custom workflows in that they run outside of Atlantis commands and do not surface their output back to the PR as a comment. They can be used to customize success or failure status via the OUTPUT_STATUS_FILE environment variable. Hooks are configured in repos.yaml under the repos key in Server-Side Repo Config.

  6. Set Multiple Dynamic Variables with multienv Command

    The multienv command runs a custom command and adds printed environment variables to subsequent steps. Output format must be: EnvVar1Name=value1,EnvVar2Name=value2. Use output: hide to suppress the message about added variables. Example: - multienv: custom-command (compact) or full form with shell and shellArgs.

  7. Configure Atlantis Server with Environment Variables, Config File, or Flags

    Atlantis server can be configured using three methods: command-line flags, environment variables, or a YAML config file. All flags support environment variables (use true/false for boolean flags). For YAML config, use --config /path/to/config.yaml with keys matching flag names. Note: --atlantis-url uses ATLANTIS_ATLANTIS_URL, not ATLANTIS_URL.

  8. Atlantis Locking Overview

    Atlantis locks the directory and Terraform workspace when plan is run. The lock remains until the pull request is merged or closed, or the plan is manually deleted. Only the specific directory and workspace are locked, not the entire repository. If another user attempts to plan on the same directory and workspace in a different PR, they will see an error linking to the PR that holds the lock.

  9. Installation Prerequisites

    Before production installation, verify your Terraform setup meets Atlantis requirements. Generate access credentials for your specific Git host (GitHub, GitLab, Gitea, Bitbucket, or Azure DevOps). Create a webhook secret that Atlantis will use to validate incoming webhooks from your Git host.

  10. Why Use Atlantis Locking

    Two reasons: (1) Since atlantis apply runs before PR merge, your main branch doesn't represent the latest infrastructure state. Locking ensures no other changes occur until the PR is merged. This also allows re-plan/re-apply multiple times if issues arise, unlike applying on merge where a failed apply would require a new PR to fix. (2) If a plan is already in progress, other users won't see a plan that becomes invalid after the in-progress plan is applied.

  11. Unlocking via Plan Comment Link

    At the bottom of the plan comment, click the link that says "To discard this plan click here". This takes you to the lock detail view where you can click "Discard Plan and Unlock" to delete the lock. After discarding, you must run plan again before running apply.

  12. Viewing Active Locks

    Go to the URL where Atlantis is hosted to view all active locks. Click on any lock to see its details including which PR holds the lock and when it was created.