Integration Guide – GitHub Cloud

What this guide covers

• Connecting GitHub using the GitHub App (recommended)
• Understanding why LinearB requests GitHub permissions
• Connecting GitHub using a Personal Access Token (PAT)
• Required permissions for Classic and Fine-grained PATs
• Webhook alternatives when permissions are restricted
• Reauthorizing an expired GitHub token

Before you begin

• LinearB Admin role
• GitHub organization access
• Organization owner or administrator permissions (required to install the GitHub App or create a PAT)

The LinearB GitHub App is the recommended way to connect GitHub Cloud to LinearB. It is installed in your GitHub organization and is granted access only to the repositories and permissions required to collect repository activity.

LinearB uses these permissions to read repository metadata, commits, branches, pull requests, reviews, and webhook events. This information powers delivery metrics, AI insights, workflow automations, and notifications such as WorkerB.

The GitHub App is the recommended way to connect GitHub Cloud to LinearB. In LinearB, this connection is initiated by clicking Authorize GitHub, which starts the GitHub App installation flow.

1. In LinearB, go to Settings → Company Settings and select the Git tab.
2. Click Add Integration.
3. Select GitHub.
4. Click Authorize GitHub.
5. If you have the required permissions, install the GitHub App in your GitHub organization. Otherwise, request approval from a GitHub organization administrator.
6. Select the repositories you want LinearB to access.
7. Complete the installation and return to LinearB.

Once connected, LinearB begins syncing repository data and enables engineering metrics, AI insights, workflow automations, and WorkerB notifications.

If you cannot install the GitHub App, you can connect GitHub using a Personal Access Token (PAT).

Step 1. Create a Personal Access Token in GitHub

1. Log in to GitHub.
2. Create either a Fine-grained PAT or a Classic PAT.
3. Set an expiration date. To avoid data gaps, we recommend choosing a long expiration period or no expiration (if supported).

Required permissions

If write:repo-hook cannot be granted, see Alternative to write:repo-hook permission below.

4. Copy the token. You will not be able to view it again.

Step 2. Add the GitHub PAT to LinearB

1. In LinearB, go to Settings → Company Settings → Git.
2. Click Add Integration and select GitHub.
3. Select Classic or Fine-grained token.
4. Paste the PAT and click Connect.

LinearB uses repository webhooks for real-time data collection. If write:repo-hook cannot be granted, choose one of the following options:

Option 1: Delayed sync

LinearB syncs data every 2 hours instead of in real time. Metrics and notifications may be delayed.

Option 2: Organization-level webhook

Install a GitHub organization-level webhook to bypass repository-level permissions. See Installing a GitHub Organization-Level Webhook .

1. Create a new PAT in GitHub.
2. In LinearB, go to Settings → Company Settings → Git.
3. Open the three-dot menu next to the GitHub integration.
4. Select Reauthorize Git and paste the new token.

LinearB resumes syncing data using the new token.

• Verify that the GitHub account has access to the selected repositories.
• Ensure the required GitHub App permissions or PAT scopes have been granted.
• If a GitHub App installation requires approval, contact your GitHub organization administrator.
• Contact support@linearb.io or join the Dev Interrupted Discord .