Skip to main content

GitHub App Integration

The Overmind GitHub App connects your organization's repositories to Overmind and provides two capabilities:

  1. PR Commenting -- automatically posts blast radius results and risks as a comment on your pull request when analysis completes. No CI wait time or polling required.
  2. GitHub Signals -- streams pull request metadata, deployment cadence, and CI signal history into the Overmind platform for richer risk analysis.

GitHub App integration status showing enabled installation

Requirements​

  • GitHub organization owner or admin permissions to install the app.
  • An Overmind account with access to the target organization.
  • Overmind CLI v1.33.0 or later.
  • The App must have pull_requests:write permission on target repositories for PR commenting.
  • Pass through a ticket link when submitting a plan. The Pull Request URL or GitHub Actions Run URL is recommended, as this is how the App identifies which PR to comment on.

Installation​

  1. From the Overmind application, navigate to Settings → Integrations → GitHub.
  2. Select Install GitHub App. You will be redirected to GitHub to approve permissions.
  3. Choose the organization and repositories Overmind should monitor.
  4. Confirm the installation. The integration page will show an Enabled status once complete.

Overmind begins indexing repository metadata immediately after installation. Initial synchronization may take several minutes depending on repository size.

Organizations that require admin approval​

If your GitHub organization requires admin approval for app installations, you will see a Pending status on the integration page after requesting the installation. Once your organization admin approves the request in GitHub, the integration transitions to Enabled automatically -- no further action is needed from you.

Configure GitHub Signals​

After installation, create .overmind/signal-config.yaml in your Terraform project. This file defines how GitHub deployments map to Overmind change analysis.

github_organisation_profile:
  primary_branch_name: main

Configuration options:

  • primary_branch_name: The name of the primary branch for the repository

See the CLI Configuration guide for file templates and CLI flags (--signal-config) that load this configuration during plan submission.

PR Commenting​

When the --comment flag is passed to submit-plan or start-analysis, Overmind automatically posts blast radius results and identified risks as a comment on the pull request once analysis completes.

How it works​

  1. You run overmind changes submit-plan --comment --ticket-link "$PR_URL" tfplan.json (or pass --comment to start-analysis in a multi-plan workflow).
  2. The CLI sends the plan to Overmind and returns immediately -- no waiting or polling.
  3. Overmind runs blast radius analysis asynchronously.
  4. When analysis completes, the GitHub App posts a formatted comment on the PR identified by the --ticket-link.

GitHub Actions integration​

The submit-plan GitHub Action defaults to comment: true and automatically detects whether the GitHub App is installed:

  • GitHub App installed: The action exits immediately. The App posts results asynchronously -- faster CI, no polling.
  • GitHub App not installed: The action falls back to waiting for analysis and posting a sticky PR comment (existing behavior).

No workflow changes are needed. Installing the App is sufficient to migrate to async PR commenting.

Atlantis integration​

For Atlantis workflows (including parallel multi-project planning), pass --comment to submit-plan or start-analysis:

overmind changes start-analysis \
  --comment \
  --ticket-link "$PULL_REQUEST_URL"

See the Atlantis integration guide for complete examples.

Permissions​

The App requires pull_requests:write on the target repository to post comments. This permission is requested during installation. If the permission is missing, the CLI still works but the --comment flag has no effect -- you can fall back to using get-change to retrieve results and post them yourself.

Using the Integration​

With the app installed and configuration file in place:

  1. Run overmind changes submit-plan from your Terraform repository.

  2. Overmind augments blast radius analysis with GitHub branch, PR, and deployment context.

  3. Pass --comment to have the App post results directly on the PR:

    overmind changes submit-plan --comment \
      --ticket-link "$PR_URL" \
      tfplan.json

  4. Review the resulting GitHub App Signals within the change details to understand deployment windows, automation coverage, and unusual activity.

Regenerating the Profile​

If you add or remove repositories in GitHub, return to Settings → Integrations → GitHub and choose Regenerate profile. This updates Overmind's repository inventory and recalculates organizational metrics (team size, change frequency, merge time).

Troubleshooting​

  • No PR comment appearing: Verify the App has pull_requests:write permission on the repository and that --ticket-link points to a valid PR URL. Check the change in the Overmind UI to confirm analysis completed.
  • Missing repositories: Ensure the app is installed with access to the relevant repositories. You can update permissions directly from GitHub.
  • No signals appearing: Verify signal-config.yaml is committed and readable, then resubmit the plan. Signals may take a few minutes to populate for new installations.
  • Outdated branch data: Click Regenerate profile to refresh repository metadata if branches change frequently.