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

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" \
              > .overmind-change-url

            # Extract Change ID from URL
            CHANGE_URL=$(cat .overmind-change-url)
            CHANGE_ID=$(echo "$CHANGE_URL" | grep -o '[0-9a-f]\{8\}-[0-9a-f]\{4\}-[0-9a-f]\{4\}-[0-9a-f]\{4\}-[0-9a-f]\{12\}')

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

            echo "✓ Plan submitted to Overmind"
            echo "Change ID: $CHANGE_ID"
            echo "View at: $CHANGE_URL"

            # Optional: Wait for analysis to complete and get details
            # This will block until risk calculation is finished
            echo ""
            echo "Fetching blast radius analysis..."
            overmind changes get-change --change "$CHANGE_URL" --format markdown || \
              echo "Could not retrieve change details"

    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-change-url
            fi

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" \
              --blast-radius-link-depth 3 \
              > .overmind-change-url

            # Get the change URL and fetch details
            CHANGE_URL=$(cat .overmind-change-url)
            
            echo "Waiting for blast radius analysis..."
            overmind changes get-change --change "$CHANGE_URL" --format markdown

Waiting for Analysis Results

By default, submit-plan returns immediately after submitting the plan, allowing Atlantis to continue. If you want to wait for the blast radius analysis to complete and display the results in your PR comment, use get-change:

- run: |
    terraform show -json $PLANFILE | \
    overmind changes submit-plan - \
      --ticket-link "$PULL_REQUEST_URL" \
      > .overmind-change-url

    CHANGE_URL=$(cat .overmind-change-url)
    
    # Wait for analysis and display results
    overmind changes get-change --change "$CHANGE_URL" --format markdown

The get-change command will:

Wait for the blast radius calculation to complete (up to 10 minutes by default)
Return a markdown-formatted summary of risks and affected resources
Display the summary in your Atlantis PR comment

Note: This increases the time before Atlantis posts results, but provides immediate visibility into risks without requiring users to click through to the Overmind UI.

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: |
    terraform show -json $PLANFILE | \
    overmind changes submit-plan -

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" \
              --blast-radius-link-depth 5 \
              --blast-radius-max-items 1000 \
              > .overmind-change-url

            # Extract Change ID from URL
            CHANGE_URL=$(cat .overmind-change-url)
            CHANGE_ID=$(echo "$CHANGE_URL" | grep -o '[0-9a-f]\{8\}-[0-9a-f]\{4\}-[0-9a-f]\{4\}-[0-9a-f]\{4\}-[0-9a-f]\{12\}')

            if [ -z "$CHANGE_ID" ]; then
              echo "Failed to extract change ID from URL"
              cat .overmind-change-url
              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:

Verify the change URL was written to .overmind-change-url
Check that the URL format matches: https://app.overmind.tech/changes/UUID/blast-radius
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​

Environment Setup​

Configuration Options​

Workflow Customization​

Waiting for Analysis Results​

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​