Skip to main content
Connect GitHub so investigations can inspect code changes, pull requests, CI failures, files, and releases in selected repositories. Access is read-only and follows a GitHub App installation.

​
What OpenCluster uses it for

GitHub helps establish what changed near an incident, whether a change passed CI, what a pull request intended, and what configuration or release was present. OpenCluster only sees repositories selected for the App installation.

​
Prerequisites

  • Permission to install apps on the GitHub account or organization you want to connect.
  • The Admin role in OpenCluster.
  • For self-hosted deployments: a GitHub App configured for the deployment.

​
GitHub App permissions

No write permission is required.

​
Connect

1

Press Connect GitHub

In Integrations, choose GitHub, then Connect GitHub. OpenCluster sends you to GitHub.
2

Choose the account and repositories

GitHub asks which account to install on, which repositories OpenCluster may read, and shows the permissions above for approval. The choice is made in GitHub.
3

Land back in OpenCluster

GitHub returns you to OpenCluster, which validates the installation with GitHub, checks its repository access, and shows it as verified. There is no second step and no ID to copy.
Connect once for each GitHub account or organization. Repeating the flow for an account that is already connected re-checks it instead of adding a duplicate — which is also what happens when you change an existing installation’s repositories. OpenCluster stores no GitHub installation token. It creates short-lived installation tokens on demand from the deployment’s App.

​
Configure the App for a self-hosted deployment

Create the App in GitHub with the permissions above. It needs no webhook. Generate a private key, then set the deployment’s App ID and private-key file as described in the configuration reference. Set the App’s setup URL to https://YOUR-OPENCLUSTER/api/v1/integrations/connect/callback and enable redirect on update. The callback URL must match the deployment’s public URL exactly, scheme included. The private key stays on the deployment.

​
Verify

Verification checks the App installation and its repository selection. verified means GitHub answered for the installation; individual Tools remain limited by verified grants. A suspended, removed, or inaccessible installation is failed until verification succeeds.

​
Change which repositories are read

Repository selection lives in GitHub, not in OpenCluster. Open the installation’s settings from the link on the integration, change the selection there, and the next investigation reads the new set. Nothing needs to be re-entered here.

​
During investigations

OpenCluster may read repository metadata, commits and diffs, pull requests, checks, workflow runs and failing-job log tails, file contents, or published releases. Reads that support time windows are clamped to the incident window. The path depends on the incident; all repositories and data types are not read automatically.

​
Limitations

  • No write operations and no code search. No write permission is requested at all.
  • Reads are limited to the repositories the installation selected. A read outside that selection says so rather than failing silently.
  • Large files, logs, and diffs are bounded; truncation is marked.
  • GitHub’s repository, file, diff, and API rate limits still apply.
  • Release reads include published releases, not every tag.
  • Changing the App’s selected repositories changes what future investigations can access. That change is made in GitHub.

​
Troubleshooting

  • Deployment has no GitHub App: configure the App ID and private-key file, then restart OpenCluster.
  • The connection could not be completed: the link expired or was already used. Press Connect GitHub again.
  • Could not confirm you administer this installation: the GitHub account that authorized the connection cannot administer the account being connected. Sign in to GitHub as someone who can, then connect again.
  • Installation not found: confirm the ID belongs to this App and that the App is still installed.
  • No longer installed: the App was uninstalled or its access was revoked in GitHub. Connect again.
  • No repositories: select at least one repository in the installation settings.
  • Rate limited: wait for GitHub’s limit to reset, then verify or investigate again.

​
Rotate or disconnect

For a self-hosted GitHub App, generate a replacement private key, replace the mounted private-key file, restart the control plane, and verify the Integration before revoking the old key. Existing Integration reads use installation tokens created from the App private key. Disable the integration to remove GitHub from new investigations while retaining the record. Deletion is refused when investigation records depend on it. Uninstalling the App in GitHub removes OpenCluster’s access immediately and independently; the integration then reports that it is no longer installed.

​
Next step

Connect an alert source, then run the first Investigation with GitHub available as evidence.

​
Availability

GitHub is available in OSS v0.1 when the deployment has a GitHub App. GitHub and its mark belong to GitHub, Inc.