Atlantis

intermediate

Terraform pull request automation for teams.

Overview

Atlantis is an open-source Terraform pull request automation tool that brings GitOps workflows to infrastructure management. Originally developed by Hootsuite and now maintained by the community, Atlantis automatically runs terraform plan on pull requests and allows controlled terraform apply operations through PR comments, ensuring infrastructure changes follow proper code review processes. This Docker configuration provides a containerized Atlantis server that integrates with GitHub or GitLab repositories to automate Terraform workflows. The setup includes webhook handling for repository events, persistent data storage for Terraform state and plans, and environment-based configuration for repository access control. Teams use this deployment to enforce infrastructure-as-code best practices, eliminate manual Terraform operations, and maintain audit trails of all infrastructure changes through version control systems.

Key Features

Automated terraform plan execution on pull request creation and updates
Comment-driven terraform apply operations with 'atlantis apply' commands
Multi-repository support with configurable allowlist for security control
Terraform state locking to prevent concurrent modifications during operations
Custom workflow support through atlantis.yaml configuration files
Built-in approval requirements before infrastructure changes can be applied
Integration with GitHub and GitLab webhook systems for real-time PR monitoring
Plan artifact storage and visualization directly in pull request comments

Common Use Cases

1DevOps teams implementing infrastructure-as-code governance and review processes
2Organizations requiring approval workflows for cloud resource provisioning changes
3Multi-environment Terraform deployments needing controlled promotion pipelines
4Teams migrating from manual Terraform operations to automated GitOps workflows
5Startups establishing infrastructure change management without dedicated tools
6Enterprise environments requiring audit trails for compliance and security reviews
7Development teams collaborating on shared infrastructure components and modules

Prerequisites

GitHub or GitLab repository with admin access for webhook configuration
Personal access token with repository permissions for API integration
Terraform repositories with proper backend configuration for state management
Domain name or public IP address for webhook endpoint accessibility
Basic understanding of Terraform workflows and pull request processes
At least 512MB RAM for container operations and Terraform plan storage

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  atlantis: 
3    image: ghcr.io/runatlantis/atlantis:latest
4    container_name: atlantis
5    restart: unless-stopped
6    ports: 
7      - "4141:4141"
8    environment: 
9      ATLANTIS_GH_USER: ${GITHUB_USER}
10      ATLANTIS_GH_TOKEN: ${GITHUB_TOKEN}
11      ATLANTIS_GH_WEBHOOK_SECRET: ${WEBHOOK_SECRET}
12      ATLANTIS_REPO_ALLOWLIST: ${REPO_ALLOWLIST}
13      ATLANTIS_ATLANTIS_URL: ${ATLANTIS_URL}
14    volumes: 
15      - atlantis_data:/atlantis
16
17volumes: 
18  atlantis_data:

.env Template

.env

1GITHUB_USER=your-bot-user
2GITHUB_TOKEN=ghp_xxxxxxxxxxxx
3WEBHOOK_SECRET=your-webhook-secret
4REPO_ALLOWLIST=github.com/your-org/*
5ATLANTIS_URL=https://atlantis.yourcompany.com

Usage Notes

1Docs: https://www.runatlantis.io/docs/
2Access at http://localhost:4141
3Configure GitHub/GitLab webhook to ${ATLANTIS_URL}/events
4Comment 'atlantis plan' on PRs to preview Terraform changes
5Comment 'atlantis apply' after plan approval to apply changes
6atlantis.yaml in repo root for custom workflows and project config

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  atlantis:
5    image: ghcr.io/runatlantis/atlantis:latest
6    container_name: atlantis
7    restart: unless-stopped
8    ports:
9      - "4141:4141"
10    environment:
11      ATLANTIS_GH_USER: ${GITHUB_USER}
12      ATLANTIS_GH_TOKEN: ${GITHUB_TOKEN}
13      ATLANTIS_GH_WEBHOOK_SECRET: ${WEBHOOK_SECRET}
14      ATLANTIS_REPO_ALLOWLIST: ${REPO_ALLOWLIST}
15      ATLANTIS_ATLANTIS_URL: ${ATLANTIS_URL}
16    volumes:
17      - atlantis_data:/atlantis
18
19volumes:
20  atlantis_data:
21EOF
22
23# 2. Create the .env file
24cat > .env << 'EOF'
25GITHUB_USER=your-bot-user
26GITHUB_TOKEN=ghp_xxxxxxxxxxxx
27WEBHOOK_SECRET=your-webhook-secret
28REPO_ALLOWLIST=github.com/your-org/*
29ATLANTIS_URL=https://atlantis.yourcompany.com
30EOF
31
32# 3. Start the services
33docker compose up -d
34
35# 4. View logs
36docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/atlantis/run | bash

Troubleshooting

Webhook events not triggering plans: Verify ATLANTIS_URL matches the configured webhook endpoint and is publicly accessible
Permission denied errors during terraform operations: Check that GITHUB_TOKEN has sufficient repository permissions and can access Terraform backends
Plans failing with provider authentication errors: Ensure AWS/Azure/GCP credentials are available through environment variables or mounted service account files
Repository not recognized by Atlantis: Confirm the repository URL is included in REPO_ALLOWLIST environment variable with proper formatting
Atlantis server returns 500 errors: Check container logs for webhook secret validation failures and verify WEBHOOK_SECRET matches GitHub configuration
Terraform state locking issues: Ensure backend supports locking and no manual terraform processes are holding locks on the same state files

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

atlantis

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download