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

For additional deployment intelligence based on your organization's GitHub behavior, consider installing the Overmind GitHub App. The GitHub App provides contextual signals about deployment timing, branch patterns, and automation that complement the GitHub Actions integration.

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 Account 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
    auto-tag-rules: .overmind/auto-tag-rules.yaml
    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 Tags

Categorize your changes with tags:

- uses: overmindtech/actions/submit-plan@main
  with:
    ovm-api-key: ${{ secrets.OVM_API_KEY }}
    plan-json: ./tfplan.json
    tags: 'environment=production,team=platform'

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
          auto-tag-rules: .overmind/auto-tag-rules.yaml
          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.