🎥 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:
- Download the CLI from here: https://github.com/overmindtech/cli/releases
- Set the
OVM_API_KEY
environment variable to your API Key - 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'
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
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
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.
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
Install nektos/act with gh extension install https://github.com/nektos/gh-act
and run
# install act with: gh extension install https://github.com/nektos/gh-act
# log into gh CLI with: gh auth login
# the medium image works well for testing
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.