Github Actions

💡 NOTE: For the latest details check out Github

Integrating the Overmind Github actions means that every PR gets automatically scanned and any infrastructure related risks identified. As soon as you create a PR, Overmind gets straight to work and puts anything important front and center.

Enhanced with GitHub App

The submit-plan action automatically detects when the Overmind GitHub App is installed on your repository:

• With the GitHub App: The action exits immediately after submitting the plan. The GitHub App posts blast radius results and risks as a PR comment asynchronously -- faster CI runs with no polling.
• Without the GitHub App: The action falls back to waiting for analysis to complete and posting results as a sticky PR comment (existing behavior).

No workflow changes are needed. Simply install the GitHub App and your existing workflows automatically benefit from faster CI and app-posted comments.

The GitHub App also provides contextual signals about deployment timing, branch patterns, and automation that enrich risk analysis.

Configuring

1. Setup your GitHub Actions in your .github folder. For example here is our terraform-example repository's automatic.yml workflow.

2. You can use the GitHub Action's secret store to provide the API key for the Overmind CLI.

3. Next, configure the actions to install the CLI and submit the plan to Overmind

   - uses: overmindtech/actions/install-cli@main
     with:
       version: latest
       github-token: ${{ secrets.GITHUB_TOKEN }}
   
   - uses: overmindtech/actions/submit-plan@main
     if: github.event.action != 'closed'
     id: submit-plan
     with:
       ovm-api-key: ${{ secrets.OVM_API_KEY }}
       plan-json: ./tfplan.json
       plan-output: ./terraform_log

4. Overmind ingests the plan and discovers the resources in AWS that will be affected.

5. Overmind will then create a blast radius by taking the affected resources and scanning for everything that depends on those resources.

6. Finally, Overmind calculates the risks for this change, and attaches them as a comment.

Creating an API Key

To use the Overmind CLI in CI, you need to 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., "GitHub Actions" or "CI/CD")
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. Copy the API key and create a secret called OVM_API_KEY in your GitHub repository settings

The API key will be used automatically by the GitHub Actions when you reference ${{ secrets.OVM_API_KEY }} in your workflow.

Configuration Options

You can customize the analysis behavior by adding configuration files to your repository or using additional parameters:

Using Configuration Files

Add configuration files to your repository for team consistency:

- uses: overmindtech/actions/submit-plan@main
  with:
    ovm-api-key: ${{ secrets.OVM_API_KEY }}
    plan-json: ./tfplan.json
    plan-output: ./terraform_log
    # Use team configuration files
    routine-changes-config: .overmind/routine-changes-config.yaml

Blast Radius Parameters

Control the depth and scope of analysis:

- uses: overmindtech/actions/submit-plan@main
  with:
    ovm-api-key: ${{ secrets.OVM_API_KEY }}
    plan-json: ./tfplan.json
    # Customize blast radius calculation
    blast-radius-link-depth: 3
    blast-radius-max-items: 500

Adding Labels

Apply colored labels to visually categorize changes:

- uses: overmindtech/actions/submit-plan@main
  with:
    ovm-api-key: ${{ secrets.OVM_API_KEY }}
    plan-json: ./tfplan.json
    labels: 'critical=FF0000,review=FFFF00'

Note: Labels use name=color format where color is a 6-digit hex code (e.g., FF0000 for red). See the CLI Configuration Guide for more details on tags and labels.

Action Inputs

The submit-plan action accepts these inputs:

Input	Default	Description
ovm-api-key	(required)	Overmind API key for authentication.
plan-json	tfplan.json	Path to the JSON-formatted Terraform plan file. Space-separated list for multiple files.
plan-output	tfplan.output	Path to the rendered Terraform plan output (from terraform plan | tee FILE).
comment	"true"	Post analysis results as a PR comment. Uses the GitHub App when installed (async, no CI wait), otherwise falls back to a sticky PR comment.
wait	"false"	Block until analysis completes and make results available as the message output. Useful for gating deployments or Slack notifications.
tags		Comma-separated key=value tags (e.g. env=production,team=platform).
comment-header	change	Header for the sticky PR comment. Use different values to distinguish multiple submit-plan calls on the same PR.
app		Overmind instance URL. Defaults to https://app.overmind.tech. Required for Enterprise on-prem.
number	PR number	Pull request number to post the comment on.
log	info	CLI log level.

Deprecated input

fetch-change is deprecated. Use comment and wait instead. When fetch-change is set, it is mapped to comment during the transition period.

Action Outputs

Output	Description
change-url	URL of the created change in the Overmind UI.
message	Markdown-formatted change summary. Only populated when wait: true or when the action falls back to posting a sticky comment (GitHub App not installed).
github-app-active	"true" when the GitHub App is handling PR commenting for this change; "false" otherwise.

Using outputs in subsequent steps

- uses: overmindtech/actions/submit-plan@main
  id: submit-plan
  with:
    ovm-api-key: ${{ secrets.OVM_API_KEY }}
    plan-json: ./tfplan.json
    wait: "true"

- name: Post to Slack
  if: steps.submit-plan.outputs.message != ''
  run: |
    echo "Change URL: ${{ steps.submit-plan.outputs.change-url }}"
    echo "Message: ${{ steps.submit-plan.outputs.message }}"

Complete Example Workflow

Here's a complete workflow that generates the plan and submits it with configuration:

name: Terraform Analysis
on: [pull_request]

jobs:
  plan:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4

      - uses: hashicorp/setup-terraform@v3
        with:
          terraform_wrapper: false

      - name: Terraform Init
        run: terraform init -input=false

      - name: Terraform Plan
        run: |
          terraform plan -no-color -input=false -out tfplan 2>&1 | tee terraform_log
          terraform show -json tfplan > tfplan.json

      - uses: overmindtech/actions/install-cli@main
        with:
          version: latest
          github-token: ${{ secrets.GITHUB_TOKEN }}

      - uses: overmindtech/actions/submit-plan@main
        with:
          ovm-api-key: ${{ secrets.OVM_API_KEY }}
          plan-json: ./tfplan.json
          plan-output: ./terraform_log
          blast-radius-link-depth: 3
          blast-radius-max-items: 500
          routine-changes-config: .overmind/routine-changes-config.yaml

Note: Verify parameter support in the actions repository as some configuration options may need to be implemented.

For more details on configuration files and parameters, see the CLI Configuration Guide.

A full example workflow can be found in the overmindtech/terraform-example repo.