Atlantis + Overmind Integration

Automatically analyze Terraform plans with Overmind risk assessment through Atlantis pull request workflows.

Overview

This integration adds automated blast radius analysis and complete lifecycle tracking to your Atlantis Terraform workflow. Every time you run atlantis plan, the plan is automatically submitted to Overmind for analysis. When you run atlantis apply, the change is tracked from start to completion, giving you:

• Blast radius - What resources will be affected by this change
• Risk assessment - Potential security, compliance, or operational risks
• Change impact - Dependencies and downstream effects
• Lifecycle tracking - Full visibility from plan → apply → completion
• Change history - Historical record of all infrastructure changes
• Recommendations - Suggested mitigations and best practices

Quick Start

Prerequisites

• Atlantis server (self-hosted or cloud)
• Overmind account (sign up)
• Terraform 0.12 or later

Setup

1. Get your Overmind API key from app.overmind.tech/settings/api-keys

2. Add the configuration to your repository:

   # Copy atlantis.yaml to your repository root
   cp atlantis.yaml /path/to/your/repo/
   
   # Copy the integration script
   cp scripts/overmind-integration.sh /path/to/your/repo/scripts/
   chmod +x /path/to/your/repo/scripts/overmind-integration.sh

3. Set the environment variable on your Atlantis server:

   export OVM_API_KEY="your-overmind-api-key"

4. Test it:

   • Create a PR with Terraform changes
   • Comment atlantis plan on the PR
   • View the analysis in Overmind dashboard

Local Testing (Optional)

Test the integration locally before deploying:

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

# Run the quick test
./quick-test.sh

This will create a Terraform plan and submit it to Overmind for analysis.

How It Works

Complete Lifecycle Tracking

Developer creates PR with Terraform changes
              ↓
Comments "atlantis plan" on PR
              ↓
Atlantis executes Terraform plan
              ↓
Plan submitted to Overmind (submit-plan)
              ↓
Change ID saved for apply phase
              ↓
Risk analysis available in Overmind dashboard
              ↓
Developer comments "atlantis apply"
              ↓
Change marked as starting (start-change)
              ↓
Terraform apply executes
              ↓
Change marked as complete (end-change)
              ↓
Final validation and summary retrieved

The integration provides full lifecycle tracking of infrastructure changes:

Plan Phase:

1. Executes terraform plan
2. Converts plan to JSON format
3. Submits to Overmind via submit-plan
4. Saves the Change ID to .overmind-change-id file
5. Links to PR and adds repository tags

Apply Phase:

1. Reads saved Change ID from .overmind-change-id
2. Calls start-change to mark execution beginning
3. Executes terraform apply
4. Calls end-change to mark completion
5. Retrieves final change summary
6. Cleans up temporary files

Configuration

Repository-Specific Setup

The included atlantis.yaml configures Atlantis with complete lifecycle tracking. Key sections:

Lifecycle-Tracked Workflow:

workflows:
  overmind-tracked:
    plan:
      steps:
      - init
      - plan
      - run: |
          # Submit plan and save Change ID
          terraform show -json $PLANFILE | \
          overmind changes submit-plan - \
            --ticket-link "$PULL_REQUEST_URL" \
            --tags "atlantis=true,repo=$BASE_REPO_NAME" \
            --format json > .overmind-response.json
          
          CHANGE_ID=$(cat .overmind-response.json | grep -o '"uuid":"[^"]*"' | head -1 | cut -d'"' -f4)
          echo "$CHANGE_ID" > .overmind-change-id
    
    apply:
      steps:
      - run: |
          # Mark change as starting
          CHANGE_ID=$(cat .overmind-change-id)
          overmind changes start-change --uuid "$CHANGE_ID"
      - apply
      - run: |
          # Mark change as complete
          CHANGE_ID=$(cat .overmind-change-id)
          overmind changes end-change --uuid "$CHANGE_ID"
          overmind changes get-change --uuid "$CHANGE_ID" --format markdown

The workflow saves the Change ID during plan to a file (.overmind-change-id), which is then used during apply to track the complete lifecycle.

Fallback Hook (for repositories without custom workflows):

repos:
- id: /.*/
  post_workflow_hooks:
    - run: |
        # Simple post-plan submission for basic integration
        if [ "$COMMAND_NAME" = "plan" ]; then
          terraform show -json "$PLANFILE" | \
          overmind changes submit-plan - \
            --ticket-link "$PULL_REQUEST_URL"
        fi

Server-Side Setup

For centralized configuration across multiple repositories, use atlantis-server.yaml:

repos:
- id: github.com/your-org/your-repo
  post_workflow_hooks:
    - run: ./scripts/overmind-integration.sh

Place scripts/overmind-integration.sh on your Atlantis server and reference it in your server configuration.

Features

• Complete Lifecycle Tracking - Track changes from plan → apply → completion
• Risk Analysis - Every plan analyzed for blast radius and impact
• Change Status Updates - Real-time status in Overmind (planned, running, complete)
• Automatic Tagging - Plans tagged with repo, PR, and workspace info
• Targeted Plans - Supports atlantis plan -- -target=resource.name
• Secure - API key-based authentication
• Detailed Insights - View full analysis in Overmind dashboard with historical tracking

Environment Variables

Required

Variable	Description
OVM_API_KEY	Your Overmind API key

Optional

Variable	Description	Default
OVM_LOG_LEVEL	Log level for Overmind CLI	info

Auto-Populated by Atlantis

These variables are automatically provided by Atlantis:

• PLANFILE - Path to the generated plan file
• PULL_REQUEST_URL - URL of the pull request
• BASE_REPO_NAME - Repository name
• BASE_REPO_OWNER - Repository owner
• PULL_NUM - Pull request number
• WORKSPACE - Terraform workspace name

Targeted Plans

The integration supports Atlantis targeted plans:

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

Overmind will analyze only the targeted resources and their dependencies.

Troubleshooting

Hook Not Executing

Check Atlantis logs:

atlantis server --log-level debug

Verify atlantis.yaml is in repository root and committed.

Plan Submission Fails

Verify API key is set:

echo $OVM_API_KEY

Test connectivity:

curl -I https://app.overmind.tech

Check Overmind CLI installation:

overmind --version

No Analysis Appearing

The integration submits plans to Overmind but doesn't post comments to PRs by default. View analysis at:

• Overmind Dashboard
• Use the change link from Atlantis logs

Apply Fails with "Change ID not found"

This occurs when the .overmind-change-id file is missing:

Cause: Plan and apply ran in different Atlantis workspaces, or file was manually deleted

Solution:

1. Run atlantis plan again to generate a new Change ID
2. Then run atlantis apply

Prevention: Ensure you're using the same workspace for plan and apply

Change Not Marked as Complete

If end-change fails:

Check:

# Verify change exists in Overmind
overmind changes get-change --uuid <CHANGE_ID>

Common Issues:

• Network connectivity to Overmind API
• Invalid or expired Change ID
• API key permissions

Docker Setup (Development)

For local development and testing with Docker:

# 1. Set environment variables in .env file
cp .env.example .env
# Edit .env and add your OVM_API_KEY

# 2. Start Atlantis
docker compose up

# 3. Configure webhook in your GitHub repo
# URL: http://localhost:4141/events (or use ngrok for external access)

See docker-compose.yml for configuration details.

Files

File	Purpose
atlantis.yaml	Repository-specific Atlantis configuration
atlantis-server.yaml	Example server-side configuration
scripts/overmind-integration.sh	Reusable integration hook script
docker-compose.yml	Docker setup for local testing
quick-test.sh	Local testing script
main.tf	Example Terraform configuration

Security Considerations

• Never commit your .env file or API keys
• Store OVM_API_KEY in a secure secrets manager in production
• Use read-only API keys when possible
• Rotate API keys regularly
• Review Overmind's security documentation

Support

• Documentation: docs.overmind.tech
• Atlantis Docs: www.runatlantis.io
• Issues: Open an issue in this repository
• Overmind Support: support@overmind.tech

License

This example repository is provided as-is for demonstration and integration purposes.

---

Ready to get started? Get your API key at app.overmind.tech/settings/api-keys