Skip to main content

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:

  1. Converts the plan to JSON format
  2. Submits it to Overmind for blast radius analysis
  3. Saves a Change ID for tracking
  4. 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:

  1. Before apply: Marks the change as "starting" and captures a snapshot of current infrastructure state
  2. During apply: Atlantis deploys your infrastructure changes normally
  3. 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.

Parallel Planning (Multi-Project)​

If your Atlantis setup manages multiple projects that plan in parallel (e.g. networking, compute, and database modules in the same repository), you can accumulate all plans into a single Overmind Change before triggering analysis.

The workflow uses two commands:

  1. Each project's plan step calls submit-plan --no-start to store its planned changes without starting analysis
  2. A post-workflow hook calls start-analysis --comment to trigger analysis once all projects have been planned

All plans with the same --ticket-link accumulate on the same Change automatically.

atlantis.yaml in your repository:

version: 3
projects:
  - name: networking
    dir: ./networking
    workflow: overmind-parallel
  - name: compute
    dir: ./compute
    workflow: overmind-parallel
  - name: database
    dir: ./database
    workflow: overmind-parallel

workflows:
  overmind-parallel:
    plan:
      steps:
        - init
        - plan
        - run: |
            terraform show -json $PLANFILE > plan.json
            overmind changes submit-plan --no-start \
              --ticket-link "$PULL_REQUEST_URL" \
              plan.json

            echo "Plan submitted to Overmind (analysis deferred)"

    apply:
      steps:
        - run: |
            if [ -f .overmind-change-id ]; then
              CHANGE_ID=$(cat .overmind-change-id)
              overmind changes start-change --uuid "$CHANGE_ID" || true
            fi

        - apply

        - run: |
            if [ -f .overmind-change-id ]; then
              CHANGE_ID=$(cat .overmind-change-id)
              overmind changes end-change --uuid "$CHANGE_ID" || true
              rm -f .overmind-change-id
            fi

Atlantis server-side config (repos.yaml or server flags) -- add a post-workflow hook that triggers analysis after all projects have been planned:

repos:
  - id: /.*/
    post_workflow_hooks:
      - run: |
          overmind changes start-analysis \
            --comment \
            --ticket-link "$PULL_REQUEST_URL"

When the Overmind GitHub App is installed, the --comment flag causes Overmind to post blast radius results directly on the PR once analysis completes. No waiting or polling is needed in Atlantis.

Without the GitHub App, omit --comment and use get-change to retrieve results in a subsequent step (see Waiting for Analysis Results below).

See the CLI Commands reference for full flag documentation on submit-plan and start-analysis.

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. There are two ways to get analysis results onto your PR:

Option 1: GitHub App (recommended) -- pass --comment and the Overmind GitHub App posts results directly on the PR when analysis completes. No waiting or polling needed:

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

Option 2: Poll with get-change -- wait for analysis in the plan step and display results in the Atlantis PR comment:

- 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 the configured timeout)
  • Return a markdown-formatted summary of risks and affected resources
  • Display the summary in your Atlantis PR comment

Note: Option 2 increases the time before Atlantis posts results, but provides immediate visibility into risks without requiring users to click through to the Overmind UI. Option 1 avoids this delay entirely.

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​

  1. Create infrastructure changes - Modify Terraform files in your repository
  2. Open pull request - Submit changes for review
  3. Run analysis - Comment atlantis plan on the PR
  4. Review results:
    • Atlantis shows Terraform plan output
    • Overmind provides blast radius and risk assessment
    • Change ID displayed in Atlantis output
  5. View detailed analysis - Click link to Overmind dashboard
  6. Deploy changes - Comment atlantis apply after approval
  7. 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​

  1. Create a test PR with simple Terraform changes
  2. Comment atlantis plan on the PR
  3. Verify in Atlantis logs:
    • Plan submission succeeds
    • Change ID is extracted and saved
    • Overmind link appears in output
  4. Check Overmind UI for your change
  5. Comment atlantis apply to test full lifecycle
  6. 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​

  1. Verify Atlantis Configuration:

    # Check atlantis.yaml syntax
    atlantis validate

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

  2. Test Overmind CLI:

    # Check CLI installation
    overmind --version

    # Test authentication
    overmind auth status

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

  3. 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​

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