# Atlantis — Terraform Pull Request Automation for Teams

> Turn `terraform plan` and `apply` into GitHub/GitLab pull-request comments with locking, policy checks, and full audit history.

## Install

Save in your project root:

# Atlantis — Terraform Pull Request Automation for Teams

## Quick Use
```bash
# Run the server (single binary)
atlantis server 
  --atlantis-url="https://atlantis.example.com" 
  --gh-user=my-bot --gh-token=$GH_TOKEN 
  --gh-webhook-secret=$WEBHOOK_SECRET 
  --repo-allowlist="github.com/my-org/*"

# In a pull request, comment:
atlantis plan              # run `terraform plan`
atlantis apply             # run `terraform apply` after approval
atlantis unlock            # release the state lock
```

## Introduction
Atlantis is a self-hosted server that listens to Git webhooks, runs Terraform/OpenTofu in response to pull-request comments, and streams the output back as a comment. It gives teams a shared, audited, chat-ops workflow for infrastructure changes without giving every developer direct AWS/GCP credentials.

## What Atlantis Does
- Receives GitHub, GitLab, Bitbucket, or Gitea webhooks on PR open/sync/comment
- Clones the PR branch into a workspace and runs `plan`/`apply`
- Posts the plan output back as a PR comment, with collapsible diff
- Locks the state so only one PR can apply to a given workspace at a time
- Enforces OPA/Conftest policies via `server-side` policy checks before apply

## Architecture Overview
Atlantis is a single Go binary, typically deployed as a Kubernetes Deployment or a systemd unit behind TLS. It maintains a per-repo/per-workspace lock in BoltDB (or Redis in HA), shells out to `terraform`/`tofu` binaries it downloads per-project, and uses your VCS API for comment posting. Sensitive AWS credentials live on the Atlantis host via IRSA / workload identity, not in developer laptops.

## Self-Hosting & Configuration
- Helm chart: `helm install atlantis runatlantis/atlantis -f values.yaml`
- `atlantis.yaml` per repo defines projects, workspaces, terraform version, workflow hooks
- `server-side-config` lets ops teams lock down what users can override per-repo
- Secrets: webhook secret, VCS token, cloud credentials via env or mounted files
- HA: share BoltDB via Redis + run multiple replicas behind a load balancer

## Key Features
- PR-native workflow — no special CI syntax; operators comment `atlantis plan`
- State locking prevents concurrent applies clobbering each other
- Policy-as-code via Conftest/OPA gates applies at plan time
- Works with Terraform, OpenTofu, Terragrunt, and custom workflow hooks
- Self-hosted — infra credentials never leave your network

## Comparison with Similar Tools
- **Terraform Cloud / HCP** — SaaS equivalent; costlier, great UI, less control
- **Spacelift / env0 / Scalr** — commercial SaaS with richer policies and dashboards
- **tfmigrate / tf-controller** — niche GitOps operators; narrower scope
- **Crossplane** — Kubernetes CRDs instead of PR workflow; different paradigm
- **Digger** — OSS alternative running inside GitHub Actions; less mature locking

## FAQ
**Q:** Does Atlantis run `apply` automatically?
A: No. By default `apply` requires a human comment and PR approval; both are configurable.

**Q:** Can one server serve many repos?
A: Yes. `--repo-allowlist` scopes repositories; `atlantis.yaml` per repo defines workspaces.

**Q:** How do I restrict who can apply?
A: Use `--require-approval` plus `allowed_workflows` in server-side config and VCS CODEOWNERS.

**Q:** Is Terragrunt supported?
A: Yes, via `terragrunt_version` and a workflow that calls `terragrunt plan` instead.

## Sources
- https://github.com/runatlantis/atlantis
- https://www.runatlantis.io

---
Source: https://tokrepo.com/en/workflows/a997170b-38ef-11f1-9bc6-00163e2b0d79
Author: AI Open Source