Skip to main content

GitHub App Integration

The Overmind GitHub App connects your organization's repositories to Overmind so that change reviews and blast radius analysis can incorporate live GitHub activity. Once installed, the app streams pull request metadata, deployment cadence, and CI signal history into the Overmind platform, enabling precise GitHub App Signals during plan submission.

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 (for GitHub App Signals support).
  • Pass through a ticket link to the Overmind GitHub App when submitting a plan. Mentioning the Pull Request URL or the GitHub Actions Run URL is recommended.

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.

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.

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. 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​

  • 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.