README.md

Overmind Actions

https://overmind.tech

🎥 Watch a demo | 📖 How it works | 🚀 Sign up | 💻 Playground | 🙌 Follow us

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?

Currently we only have an action for GitHub, but don't fear! 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. Add a step to your pipeline to create a change:

./overmind changes submit-plan \
  --title 'Pull request title goes here' \
  --description 'PR description goes here' \
  --ticket-link 'link to PR goes here' \
  --plan-json 'path/to/plan.json'

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 a Overmind Change for it, and runs Impact Analysis.

- 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

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, 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)