Skip to main content

Custom Integrations

Overmind can read in your Terraform/OpenTofu plans on every pull request and show you the potential impact ("blast radius"), as well as give a machine-generated list of risks of the change. This guide covers how to integrate Overmind into any CI/CD system using the CLI.

If you use GitHub Actions, see the GitHub Actions integration for a turnkey solution. For Atlantis, see the Atlantis integration.

Setting Up the API Key​

Before using the Overmind CLI in CI, create an API key with the required permissions:

  1. Go to Settings > API Keys and click "New API Key"
  2. Give the key a name (e.g., "CI/CD" or "Jenkins")
  3. Select the following permissions:
    • account:read
    • changes:write
    • config:write
    • request:receive
    • sources:read
    • source:write
  4. Click "Confirm" to create the API key
  5. Set the API key as an environment variable OVM_API_KEY in your CI/CD system

Single-Plan Workflow​

The simplest integration submits a single Terraform plan and starts analysis immediately:

# Generate the plan
terraform plan -out=tfplan
terraform show -json tfplan > tfplan.json

# Submit to Overmind -- starts analysis and prints the change URL
CHANGE_URL=$(overmind changes submit-plan \
  --ticket-link "$PR_URL" \
  tfplan.json)

echo "View change at: $CHANGE_URL"

To have the Overmind GitHub App post results directly on your PR as a comment, add --comment:

overmind changes submit-plan \
  --comment \
  --ticket-link "$PR_URL" \
  tfplan.json

With --comment, the CLI returns immediately and the GitHub App posts results asynchronously when analysis completes. This avoids blocking your CI pipeline.

Multi-Plan Workflow​

For CI systems that produce multiple Terraform plans in parallel (e.g. matrix builds, Atlantis multi-project, or separate plan jobs per environment), you can accumulate all plans into a single Change and trigger analysis once:

# Step 1: Each parallel job submits its plan without starting analysis
overmind changes submit-plan --no-start \
  --ticket-link "$PR_URL" \
  tfplan-networking.json

overmind changes submit-plan --no-start \
  --ticket-link "$PR_URL" \
  tfplan-compute.json

# Step 2: After all plans are submitted, trigger analysis
overmind changes start-analysis \
  --comment \
  --ticket-link "$PR_URL"

Key points:

  • All submit-plan --no-start calls with the same --ticket-link accumulate planned changes on the same Change.
  • start-analysis triggers blast radius analysis across all accumulated plans.
  • Pass --comment to either submit-plan or start-analysis to have the GitHub App post results on the PR.

Fetching Results​

Use get-change to retrieve a summary of the change, including blast radius and risks:

# Wait for analysis to complete, then print a markdown summary
overmind changes get-change \
  --change "$CHANGE_URL" \
  --format markdown

By default, get-change waits for analysis to complete before returning. To return immediately with whatever status is currently available:

overmind changes get-change \
  --change "$CHANGE_URL" \
  --format json \
  --wait=false

This is useful for polling-based workflows or dashboards that display partial results.

Deployment Lifecycle​

Wrap your deployment with start-change and end-change to capture before/after system snapshots and create a complete audit trail:

# Extract the change UUID from the URL
CHANGE_URL=$(cat .overmind-change-url)
CHANGE_ID=$(echo "$CHANGE_URL" | grep -oE '[0-9a-f-]{36}')

# Before deployment: capture pre-change state
overmind changes start-change --uuid "$CHANGE_ID"

# Run the deployment
terraform apply tfplan

# After deployment: capture post-change state
overmind changes end-change --uuid "$CHANGE_ID"

This gives you a complete change record in Overmind with planning analysis, deployment timing, and before/after infrastructure snapshots.

Further Reading​