Migrating a GitHub Integration to the LinearB GitHub App

TL;DR

This article explains how to upgrade an existing GitHub integration that connects through OAuth or a Classic Token to the LinearB GitHub App, which integrations are eligible, and how to fix a failed upgrade.

Upgrade your GitHub integration to the GitHub App

If your GitHub integration connects through OAuth or a Classic Token, you can upgrade it to use the LinearB GitHub App as its connection method. The upgrade happens in place: you keep the same integration, and all repository settings and monitoring rules are preserved.

Only LinearB admins can see and use the Upgrade to GitHub App option.

Check eligibility

The Upgrade to GitHub App option appears in the integration menu only when both conditions are met:

• The integration includes only one GitHub organization.
• The integration has fewer than 1,000 monitored repositories. Repositories in the Monitored, Processing, and Failing states all count as monitored.

Integrations with 1,000 or more monitored repositories, or with more than one GitHub organization, can't be upgraded to the GitHub App.

Before you upgrade

• The upgrade can't be undone. Once upgraded, the integration can't go back to its previous connection method.
• Webhooks aren't removed. Webhooks configured on your GitHub organization aren't affected by the upgrade. Remove them manually from GitHub after upgrading.
• Settings are preserved. All repository settings and monitoring rules stay in the integration after the upgrade.
• Organizations shared across integrations. If the same GitHub organization is used in more than one LinearB integration, repositories discovered in the other integrations won't be discovered in the GitHub App integration. Repositories are bound to the integration that discovered them.

Upgrade to the GitHub App

To upgrade your GitHub integration:

1. Navigate to Company Settings > Git > Integrations and Repositories.
2. On your GitHub integration, open the ⋮ menu and select Upgrade to GitHub App.
3. Review the confirmation dialog and click Upgrade to GitHub App.
4. LinearB redirects you to GitHub. Install the LinearB GitHub App in your GitHub organization. If you don't have the required GitHub permissions, request approval from a GitHub organization administrator.
5. Under Repository access, select All repositories. If you select specific repositories, the upgrade fails.
6. Complete the installation on GitHub and return to LinearB.

If the upgrade fails, see Troubleshoot a failed upgrade below.

Troubleshoot a failed upgrade

If the upgrade fails, your integration shows Upgrade to GitHub App failed, and LinearB displays a dialog that explains the cause.

The GitHub App doesn't have access to all repositories

You see the message: "The GitHub App does not have access to all repositories." This happens when specific repositories were selected during the GitHub App installation instead of All repositories.

To fix it:

1. Click Manage integration on GitHub.
2. Change the GitHub App's repository access to All repositories.
3. Return to LinearB and try the upgrade again.

The GitHub App was installed on a different GitHub organization

You see the message: "The GitHub App was installed on a different GitHub organization than the one being upgraded." This happens when the LinearB GitHub App was installed on a GitHub organization other than the one connected to your integration.

To fix it:

1. Click Manage integration on GitHub.
2. Reinstall the LinearB GitHub App on the GitHub organization connected to your integration.
3. Return to LinearB and try the upgrade again.