Skip to content

overmindtech/actions

Repository files navigation

Overmind

Overmind Actions

https://overmind.tech


Discord Server

🎥 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'

Example Overmind report showing the expected changes and timeline for the example PR

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

Complete 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".

api keys auth window

Give the key a name e.g. "Github Actions" and select the changes:write permission 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.

Development

Install nektos/act and run

gh act pull_request -s GITHUB_TOKEN="$(gh auth token)" -s OVM_API_KEY="${OVM_API_KEY}"

to try out the selftest action locally. It's much faster than commit/push.