Connect Your GitHub Account to LinearB

This article describes how to connect your GitHub account to LinearB. You can do so either via OAuth (recommended) or using a Personal Access Token (PAT). OAuth is the preferred method for most users, but PATs may be necessary in certain cases (e.g., if you lack admin permissions on your GitHub organization).

If you need to remove an existing GitHub connection or add additional connections, contact LinearB’s support team for assistance.

Method 1: Connect GitHub via OAuth

OAuth is the easiest and most seamless way to connect your GitHub account to LinearB. Follow these steps to authorize LinearB via OAuth:

1. Navigate to Company Settings
   1. Log in to LinearB to access the LinearB dashboard.
   2. In the dashboard side bar, click Settings to open the Company Settings window.
2. Select Git Integration
   Click the Git tab.
3. Add a New GitHub Integration
   Click Add Integration (located on the right), and select GitHub from the list of available integrations.
4. Authorize GitHub via OAuth
   On the next screen, click Authorize GitHub. If you have the necessary permissions, you'll be prompted to authorize LinearB to access your GitHub organization. If you lack permission, you will need to request authorization from an admin.
5. Choose Repositories to Sync
   Once authorized, you can select which GitHub repositories you want to sync with LinearB. After making your selection, click Connect GitHub.

Once connected, LinearB will begin syncing data from your GitHub repositories, allowing you to leverage metrics and automation features like WorkerB.

You will see a screen to authorize access to your org(s) if you have permission to do so, or to request authorization from an admin if not. Once access is granted, you will be able to select repos to sync to LinearB.

Method 2: Connect to GitHub via Personal Access Token (PAT)

If you are unable to connect via OAuth (for example, due to insufficient permissions), you can connect using a Personal Access Token (PAT) instead.

Step 1: Create a Personal Access Token in GitHub

1. Log in to GitHub
   Go to GitHub, and log in to your account.
2. Create a Personal Access Token
   Create either a fine-grained PAT or a classic PAT.

1. Set an Expiration Date
   To prevent potential data inconsistencies, it's recommended to set a GitHub token expiration date far in the future or, if supported, choose no expiration date. If a token expires, data inconsistencies may occur during the time between its expiration and the addition of a new token. Should this happen contact support@linearb.io for assistance in validating and resolving any data issues.
2. Grant Required Permissions
   Enable the following permissions for the token to work correctly with LinearB:

* If you are unable to grant write:repo-hook due to security policies, refer to the section Alternative to write:repo-hook Permission for alternative solutions.

1. Save the Token
   Once generated, copy your token. You will need this for the next step.

Step 2: Add Your GitHub Token to LinearB

1. Navigate to Company Settings
   1. Log in to LinearB to access the LinearB dashboard.
   2. In the dashboard side bar, click Settings to open the Company Settings window.
2. Select Git Integration
   Click the Git tab.
3. Add a New GitHub Integration
   Click Add Integration (located on the right), and select GitHub from the list of available integrations.
4. Enter the PAT Details
   1. Choose to option to connect with a Classic Token or a Fine Grained Token.
   2. Paste the personal access token you generated earlier into the provided field and click Connect. LinearB will begin syncing your GitHub data.

   

Alternative to write:repo-hook Permission

The write:repo-hook permission is required by LinearB to set up webhooks that allow real-time data collection from your GitHub repositories. If your organization cannot grant this permission due to security restrictions, you have two options:

Option 1: Use a Delayed Sync

If the write:repo-hook permission is excluded, LinearB will sync data every 2 hours instead of in real time. This can lead to delayed updates for metrics and notifications, especially for time-sensitive events like PR review requests.

Option 2: Install an Organization-Level Webhook

You can also configure an organization-level webhook to collect data at the organization level, which bypasses the need for repository-level webhook permissions. For more information, refer to the article Installing a GitHub Organization-Level Webhook.

Reauthorizing an Expired GitHub PAT

If your GitHub PAT expires, you will need to generate a new token and reauthorize it in LinearB:

1. Generate a New Token
   Follow the steps in the section above to generate a new PAT.
2. Reauthorize in LinearB
   1. Go to Settings > Company Settings > Git
   2. Find your existing GitHub integration, click the three dots next to it, and select Reauthorize Git.
   3. Paste your new PAT and click Save.

LinearB will begin syncing data with the new token.

Troubleshooting and Support

If you encounter any issues while connecting or reauthorizing your GitHub account, feel free to reach out to our support team at support@linearb.io. You can also join our Dev Interrupted Discord server to discuss any GitHub or development-related topics with our community.