Overmind Actions

https://overmind.tech

🎥 Watch a demo | 📖 How it works | 🚀 Sign up |

Use this GitHub Action to automatically submit each PR's changes to Overmind, reporting back the blast radius as a comment on the PR. You can see an example of what this would look like in this PR.

Not using GitHub?

We have a CLI that you can use to integrate your own CI tooling:

1. Download the CLI from here: https://github.com/overmindtech/cli/releases
2. Set the OVM_API_KEY environment variable to your API Key
3. Submit a plan:

./overmind changes submit-plan \
  --comment \
  --ticket-link 'link to PR goes here' \
  tfplan.json

For parallel planning workflows (multiple plans per change), use --no-start on each plan and start-analysis to trigger analysis once:

./overmind changes submit-plan --no-start --ticket-link "$PR_URL" plan1.json
./overmind changes submit-plan --no-start --ticket-link "$PR_URL" plan2.json
./overmind changes start-analysis --comment --ticket-link "$PR_URL"

See the custom integrations docs for more details.

Usage

The install action installs the overmind CLI.

- uses: overmindtech/actions/install-cli@main
  with:
    version: latest # Request a specific version for install. Defaults to `latest`.
    github-token: ${{ github.token }} # Avoid API limits
    github-api-url: https://ghe.company.com/api/v3 # API for GitHub Enterprise Server (optional)

The submit-plan action takes a JSON-formatted terraform plan, creates an Overmind Change for it, and runs Impact Analysis. When the Overmind GitHub App is installed, the action exits immediately and the App posts results asynchronously as a PR comment. Without the App, it falls back to polling and posting a sticky comment.

- uses: overmindtech/actions/submit-plan@main
  id: submit-plan
  with:
    ovm-api-key: ${{ secrets.OVM_API_KEY }} # Generated within Overmind
    plan-json: ./tfplan.json # Location of the plan in JSON format

Inputs

Input	Default	Description
ovm-api-key	(required)	Overmind API key.
plan-json	tfplan.json	Path to JSON plan file(s). Space-separated for multiple files.
plan-output	tfplan.output	Path to rendered plan output (terraform plan | tee FILE).
comment	"true"	Post results as a PR comment. Uses GitHub App when installed, falls back to sticky comment.
wait	"false"	Block until analysis completes and populate the message output.
tags		Comma-separated key=value tags.
comment-header	change	Sticky comment header (use different values for multiple plans on same PR).
app		Overmind instance URL (Enterprise on-prem).
number	PR number	Pull request number.
log	info	Log level.

Deprecated: fetch-change is deprecated. Use comment and wait instead.

Outputs

Output	Description
change-url	URL of the created change.
message	Markdown summary (populated when wait: true or sticky comment fallback).
github-app-active	"true" when the GitHub App is posting the PR comment.

Pre-Mortem Example

Copy this workflow to .github/workflows/overmind.yml to run terraform init, terraform plan and submit the planned changes to Overmind.

Note: This example does not include any configuration to allow terraform access to your infrastructure.

name: Terraform Validation
on: [pull_request]

jobs:
  plan:
    runs-on: ubuntu-latest
    permissions:
      contents: read # required for checkout
      pull-requests: write # create/update a comment
    concurrency:
      group: tfstate # avoid running more than one job at the same time

    steps:
      # Checkout your code
      - uses: actions/checkout@v4

      # Set up Terraform
      - uses: hashicorp/setup-terraform@v3
        with:
          terraform_wrapper: false

      - name: Terraform Init
        id: init
        shell: bash
        run: |
          terraform init -input=false

      # Run Terraform plan. Note that these commands will allow terraform to
      # log nicely and also create a plan JSON file
      - name: Terraform Plan
        id: plan
        run: |
          set -o pipefail -ex
          terraform plan -no-color -input=false -out tfplan 2>&1 \
            | tee terraform_log
          terraform show -json tfplan > tfplan.json

      # Install the Overmind CLI
      - uses: overmindtech/actions/install-cli@main
        continue-on-error: true
        with:
          version: latest
          github-token: ${{ github.token }}

      # Submit the plan. This will add a comment with the blast radius
      - uses: overmindtech/actions/submit-plan@main
        id: submit-plan
        with:
          ovm-api-key: ${{ secrets.OVM_API_KEY }}
          plan-json: ./tfplan.json
          plan-output: ./terraform_log
          tags: 'environment=dev,application=example

Creating an API Key

To create an API key to use with this action go to Account Settings > API Keys and click "New API Key".

Give the key a name e.g. "Github Actions" and select the account:read, changes:write, config:write, request:receive, sources:read and source:write permissions and click "Confirm". This will create the API key and authorize it. The key should then display as "Ready" in the UI.

You can then copy the API key and create a secret called OVM_API_KEY in Github Actions. The action will now be ready to use.

Enterprise support

For Enterprise customers, submit-plan, start-change and end-change actions support an app: key in the with section of the action which allows you to target an on-prem instance of Overmind e.g.

      - uses: overmindtech/actions/submit-plan@main
        id: submit-plan
        with:
          ovm-api-key: ${{ secrets.OVM_API_KEY }}
          plan-json: ./tfplan.json
          plan-output: ./terraform_log
          app: https://mycompany.overmind.tech

Development

To test out the selftest action, use the act tool to run it locally. That's much faster than commit/push.

• Install nektos/act with gh extension install https://github.com/nektos/gh-act
• Set OVM_API_KEY in your environment to a valid API key
• log into gh CLI with gh auth login
• To test, run gh act pull_request -s GITHUB_TOKEN="$(gh auth token)" -s OVM_TOKEN="${OVM_API_KEY}" (use the Large image for the test)