Atlantis Integration

Overmind's Atlantis integration provides automated blast radius analysis and complete lifecycle tracking for your Terraform pull request workflows. When integrated with Atlantis, every atlantis plan command automatically submits to Overmind for risk assessment, and every atlantis apply is tracked from start to completion.

How It Works

The integration hooks into your existing Atlantis workflow to automatically analyze plans and track deployments:

During `atlantis plan`

When you comment atlantis plan on a pull request, Atlantis runs your Terraform plan as usual. The integration then:

Converts the plan to JSON format
Submits it to Overmind for blast radius analysis
Saves a Change ID for tracking
Provides a link to view the full analysis

Your Terraform plan output appears in the PR comment as normal, with an additional link to the Overmind dashboard where you can explore the blast radius, review potential risks, and understand which resources will be affected.

During `atlantis apply`

When you're ready to deploy and comment atlantis apply, the integration tracks the full lifecycle:

Before apply: Marks the change as "starting" and captures a snapshot of current infrastructure state
During apply: Atlantis deploys your infrastructure changes normally
After apply: Marks the change as "complete", captures the final state, and validates the deployment

This creates a complete audit trail from planning through deployment, with before/after snapshots that help you understand exactly what changed in your infrastructure.

Installation

Prerequisites

Before setting up the integration, ensure you have:

Atlantis server (self-hosted or cloud)
An Overmind account (free signup available)
Overmind API key with changes:write scope
Terraform 0.12 or later
Access to modify your repository's atlantis.yaml

Basic Setup

The integration can be implemented in two ways: repository-specific configuration or server-wide hooks.

Option A: Repository Configuration (Recommended)

Add an atlantis.yaml file to your repository root:

version: 3
projects:
- name: infrastructure
  dir: .
  workflow: overmind-tracked

workflows:
  overmind-tracked:
    plan:
      steps:
      - init
      - plan
      - run: |
          echo "Submitting plan to Overmind..."

          # Convert plan to JSON and submit
          terraform show -json $PLANFILE | \
          overmind changes submit-plan - \
            --ticket-link "$PULL_REQUEST_URL" \
            --tags "atlantis=true,repo=$BASE_REPO_NAME,workspace=$WORKSPACE" \
            --format json > .overmind-response.json

          # Extract and save Change ID
          CHANGE_ID=$(cat .overmind-response.json | \
                      grep -o '"uuid":"[^"]*"' | \
                      head -1 | \
                      cut -d'"' -f4)

          echo "$CHANGE_ID" > .overmind-change-id

          echo "✓ Plan submitted to Overmind"
          echo "Change ID: $CHANGE_ID"
          echo "View at: https://app.overmind.tech/changes/$CHANGE_ID/blast-radius"

    apply:
      steps:
      - run: |
          # Mark change as starting
          if [ -f .overmind-change-id ]; then
            CHANGE_ID=$(cat .overmind-change-id)
            echo "▶ Starting change: $CHANGE_ID"
            overmind changes start-change --uuid "$CHANGE_ID" || \
              echo "Warning: Could not mark change as started"
          fi

      - apply

      - run: |
          # Mark change as complete
          if [ -f .overmind-change-id ]; then
            CHANGE_ID=$(cat .overmind-change-id)
            echo "✓ Marking change as complete: $CHANGE_ID"
            overmind changes end-change --uuid "$CHANGE_ID" || \
              echo "Warning: Could not mark change as complete"

            # Get final summary
            echo ""
            echo "Final Change Summary:"
            overmind changes get-change --uuid "$CHANGE_ID" --format markdown || \
              echo "Could not retrieve change summary"

            # Cleanup
            rm -f .overmind-change-id .overmind-response.json
          fi

Option B: Post-Workflow Hooks (Gradual Rollout)

For testing on specific repositories before full deployment:

repos:
- id: github.com/your-org/your-repo
  post_workflow_hooks:
    - run: |
        # Only run for plan commands
        if [ "$COMMAND_NAME" = "plan" ] && \
           [ -f "$PLANFILE" ] && \
           [ ! -f .overmind-change-id ]; then

          terraform show -json "$PLANFILE" | \
          overmind changes submit-plan - \
            --ticket-link "${PULL_REQUEST_URL}" \
            --tags "atlantis=true,repo=$BASE_REPO_NAME"
        fi

Note: Post-workflow hooks provide basic plan submission but don't track the complete lifecycle. Use repository configuration for full functionality.

Environment Setup

Configure your Atlantis server with the required environment variable:

# Required
export OVM_API_KEY="your-api-key-from-overmind-settings"

# Optional - for debugging
export OVM_LOG_LEVEL=debug

Get your API key from Overmind Settings > API Keys.

Configuration Options

Workflow Customization

Customize the integration behavior by modifying the workflow steps:

workflows:
  overmind-tracked:
    plan:
      steps:
      - init
      - plan
      - run: |
          # Add custom tags for categorization
          TAGS="atlantis=true,environment=$WORKSPACE,team=platform"

          # Include target information if specified
          if [ ! -z "$ATLANTIS_TERRAFORM_TARGET" ]; then
            TAGS="$TAGS,target=$ATLANTIS_TERRAFORM_TARGET"
          fi

          terraform show -json $PLANFILE | \
          overmind changes submit-plan - \
            --ticket-link "$PULL_REQUEST_URL" \
            --tags "$TAGS" \
            --blast-radius-link-depth 3 \
            --format json > .overmind-response.json

Targeted Plans

The integration fully supports Atlantis targeted plans:

# Analyze only specific resources
atlantis plan -- -target=aws_instance.web

Overmind will analyze the targeted resources and their dependencies. Target information is automatically captured when available:

- run: |
    TAGS="atlantis=true"
    if [ ! -z "$ATLANTIS_TERRAFORM_TARGET" ]; then
      TAGS="$TAGS,target=$ATLANTIS_TERRAFORM_TARGET"
    fi

    terraform show -json $PLANFILE | \
    overmind changes submit-plan - --tags "$TAGS"

Advanced Configuration

For teams with specific requirements:

workflows:
  overmind-tracked:
    plan:
      steps:
      - init
      - plan
      - run: |
          # Custom blast radius settings
          terraform show -json $PLANFILE | \
          overmind changes submit-plan - \
            --ticket-link "$PULL_REQUEST_URL" \
            --tags "atlantis=true,repo=$BASE_REPO_NAME" \
            --blast-radius-link-depth 5 \
            --blast-radius-max-items 1000 \
            --auto-tag-rules .overmind/auto-tag-rules.yaml \
            --format json > .overmind-response.json

          # More robust Change ID extraction using jq
          if command -v jq &> /dev/null; then
            CHANGE_ID=$(cat .overmind-response.json | jq -r '.uuid')
          else
            CHANGE_ID=$(cat .overmind-response.json | \
                        grep -o '"uuid":"[^"]*"' | \
                        head -1 | \
                        cut -d'"' -f4)
          fi

          if [ -z "$CHANGE_ID" ] || [ "$CHANGE_ID" = "null" ]; then
            echo "Failed to extract change ID"
            cat .overmind-response.json
            exit 1
          fi

          echo "$CHANGE_ID" > .overmind-change-id

Workflow Integration

Complete Development Flow

Create infrastructure changes - Modify Terraform files in your repository
Open pull request - Submit changes for review
Run analysis - Comment atlantis plan on the PR
Review results:
- Atlantis shows Terraform plan output
- Overmind provides blast radius and risk assessment
- Change ID displayed in Atlantis output
View detailed analysis - Click link to Overmind dashboard
Deploy changes - Comment atlantis apply after approval
Track lifecycle:
- Change marked as "starting" before apply
- Terraform deploys infrastructure
- Change marked as "complete" after apply
- Final summary retrieved and displayed

Testing and Validation

Local Testing

Test the integration without submitting to Atlantis:

# Set your API key
export OVM_API_KEY="your-api-key"

# Generate a plan
cd your-terraform-project
terraform init
terraform plan -out=tfplan
terraform show -json tfplan > tfplan.json

# Test Overmind submission
overmind changes submit-plan tfplan.json --ticket-link "https://github.com/org/repo/pull/123"

Pull Request Testing

Create a test PR with simple Terraform changes
Comment atlantis plan on the PR
Verify in Atlantis logs:
- Plan submission succeeds
- Change ID is extracted and saved
- Overmind link appears in output
Check Overmind UI for your change
Comment atlantis apply to test full lifecycle
Verify start-change and end-change execute properly

Debug Mode

Enable detailed logging for troubleshooting:

- run: |
    # Debug output
    echo "=== Overmind Integration Debug ==="
    echo "PLANFILE: $PLANFILE"
    echo "PULL_REQUEST_URL: $PULL_REQUEST_URL"
    echo "BASE_REPO_NAME: $BASE_REPO_NAME"
    echo "WORKSPACE: $WORKSPACE"

    # Check plan file exists
    if [ ! -f "$PLANFILE" ]; then
      echo "ERROR: Plan file not found at $PLANFILE"
      exit 1
    fi

    # Test API connectivity
    overmind auth status

    # Your integration code here...

Troubleshooting

Common Issues

Plan Submission Fails:

Verify OVM_API_KEY is set correctly in Atlantis environment
Check network connectivity to app.overmind.tech
Ensure API key has required permissions
Test CLI authentication: overmind auth status

Change ID Extraction Fails:

Install jq for more reliable parsing: apt-get install jq
Verify JSON response format in .overmind-response.json
Check Atlantis logs for error messages

Plan File Not Found:

Ensure plan step runs before custom run step
Use $PLANFILE environment variable (provided by Atlantis)
Verify Terraform initialization succeeded

Apply Phase Can't Find Change ID:

Change ID file (.overmind-change-id) must persist between plan and apply
Ensure plan and apply run in same Atlantis workspace
Check file permissions and workspace cleanup settings

Hook Not Executing:

Verify atlantis.yaml is committed to repository root
Check Atlantis server logs: atlantis server --log-level debug
Ensure workflow name matches project configuration

Debugging Steps

Verify Atlantis Configuration:

# Check atlantis.yaml syntax
atlantis validate

# View Atlantis logs
atlantis server --log-level debug

Test Overmind CLI:

# Check CLI installation
overmind --version

# Test authentication
overmind auth status

# Test plan submission
terraform show -json $PLANFILE | overmind changes submit-plan -

Check Environment Variables:

# Verify API key is set
echo $OVM_API_KEY | cut -c1-8  # Should show: ovm_api_

# Check Atlantis variables
echo $PLANFILE
echo $PULL_REQUEST_URL
echo $BASE_REPO_NAME

Docker Setup (Development)

For local Atlantis development and testing:

# docker-compose.yml
version: '3'

services:
  atlantis:
    image: ghcr.io/runatlantis/atlantis:latest
    ports:
      - "4141:4141"
    environment:
      - ATLANTIS_GH_USER=${ATLANTIS_GH_USER}
      - ATLANTIS_GH_TOKEN=${ATLANTIS_GH_TOKEN}
      - ATLANTIS_GH_WEBHOOK_SECRET=${ATLANTIS_GH_WEBHOOK_SECRET}
      - ATLANTIS_REPO_ALLOWLIST=${ATLANTIS_REPO_ALLOWLIST}
      - OVM_API_KEY=${OVM_API_KEY}
    volumes:
      - ./atlantis-data:/atlantis

Start with:

# Create .env file
cp .env.example .env
# Edit .env and add your credentials

# Start Atlantis
docker compose up

# Configure webhook in GitHub
# URL: http://localhost:4141/events

Support and Resources

Integration Repository: GitHub - atlantis-example
Atlantis Documentation: runatlantis.io
Overmind CLI: CLI Overview
Community Support: Discord

For questions about configuration or integration setup, join our community or contact support through the application interface.

How It Works​

During atlantis plan​

During atlantis apply​

Installation​

Prerequisites​

Basic Setup​

Option A: Repository Configuration (Recommended)​

Option B: Post-Workflow Hooks (Gradual Rollout)​

Environment Setup​

Configuration Options​

Workflow Customization​

Targeted Plans​

Advanced Configuration​

Workflow Integration​

Complete Development Flow​

Testing and Validation​

Local Testing​

Pull Request Testing​

Debug Mode​

Troubleshooting​

Common Issues​

Debugging Steps​

Docker Setup (Development)​

Support and Resources​