Skip to main content
Table of Contents

Integration Guide - GitHub Cloud

GitHub Cloud Integration Guide. Connect GitHub Cloud to LinearB to sync branches, commits, pull requests, and repository activity. This enables cycle time, PR metrics, DORA metrics, and automation fe…

heather.hazell
Updated by heather.hazell

GitHub Cloud Integration Guide

Connect GitHub Cloud to LinearB to sync branches, commits, pull requests, and repository activity. This enables cycle time, PR metrics, DORA metrics, and automation features such as WorkerB.

Overview

LinearB connects to GitHub using either OAuth (recommended) or a Personal Access Token (PAT). OAuth provides the simplest setup and installs the LinearB GitHub App, which configures the required webhooks for real-time updates on your selected repositories. PATs are used when OAuth is restricted or unavailable. GitHub organization-level webhooks can also be installed to ensure real-time updates, especially when token scopes cannot include webhook write permissions.

Before You Begin

  • LinearB Admin user
  • GitHub permissions:
    • For OAuth: Ability to authorize the LinearB GitHub App for your organization(s)
    • For PAT: Admin or repository-level permissions depending on the token type
  • Optional: GitHub org admin to approve OAuth requests

Expected Time: 5–10 minutes

Steps

Method 1: Connect via OAuth (Recommended)
  1. In LinearB, go to Settings → Company Settings → Git.
  2. Click Add Integration.
  3. Select GitHub.
  4. Follow the OAuth prompts in GitHub:
    • Sign in if needed.
    • Authorize the LinearB GitHub App for your GitHub organization(s).
    • Request approval from an Org Admin if you don’t have permission.
  5. Select the repositories you want LinearB to follow and click Connect GitHub.

After authorization, the LinearB GitHub App installs the necessary repository webhooks. LinearB will begin syncing commit and PR data in near real-time.

Method 2: Connect via Personal Access Token (PAT)

Create a GitHub PAT

  1. Log in to github.com.
  2. Create either a fine-grained or classic personal access token.
  3. Configure the token with the required permissions.

Classic PAT Required Scopes

  • repo
  • read:org
  • read:user
  • user:email
  • read:discussion
  • admin:repo-hook
  • read:repo-hook
  • write:repo-hook*

Fine-Grained Token Permissions

  • members:read
  • metadata:read
  • pull_requests:read
  • contents:read
  • webhooks:write

*If your security policies restrict write:repo-hook, see the “Alternative to write:repo-hook” section below.

Add the PAT to LinearB

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

Alternative to write:repo-hook

  • Option 1 — Reduced sync frequency: Omit the webhook write permission. LinearB will sync every ~2 hours instead of real time.
  • Option 2 — Install an organization-level webhook: This provides real-time updates without requiring repo-level webhook write access.
Install a GitHub Organization-Level Webhook

This webhook allows GitHub to send push, PR, tag, and branch events to LinearB. It is recommended when:

  • You cannot grant write-level webhook permissions to a PAT.
  • You want faster, real-time updates.
  • You want centralized webhook management at the org level.

Steps

  1. In GitHub, go to your Organization Settings.
  2. Open Webhooks.
  3. Click Add Webhook.
  4. Enter the payload URL provided in the LinearB documentation.
  5. Select the event types required (push, PR, tag, branch).
  6. Save the webhook.

Once installed, GitHub will deliver real-time updates to LinearB without needing repo-level webhook permissions.

Verify

How to Confirm the Integration is Working
  • Go to Settings → Company Settings → Git.
  • You should see a connected GitHub integration with a repository count.
  • Click the integration row to view synchronized repositories.
  • PRs, commits, and branches should begin appearing in Git Activity and Delivery.

Troubleshooting

Problem Cause Fix
Authorized successfully, but organization repositories are missing GitHub authentication was completed with a personal account instead of the organization account, or the wrong organization was selected during authorization. Sign out of github.com, sign back in with the correct organization account, and repeat the LinearB connection flow. During authorization, make sure you select the intended GitHub organization and grant access to the relevant repositories.
Missing repositories Token/user lacks repo access or repos not selected Open the GitHub integration → Add Repositories → select missing repos.
Data sync is delayed No webhook write permission granted Add write:repo-hook OR install an org-level webhook.
PAT expired Token expiration date reached Create a new PAT → Reauthorize Git → paste new token.
OAuth blocked or cannot authorize You are not an org admin Request approval from an organization owner during the OAuth flow.

FAQs

Can I connect multiple GitHub organizations?
Yes. Add additional integrations from Settings → Git → Add Integration.

Do I need to sync every repository?
No. Only select repositories relevant to your teams.

Do I need a PAT and OAuth?
No. Use either OAuth or a PAT — not both.

When should I install an org-level webhook?
When you cannot grant webhook write permissions to a PAT or you want real-time updates across all repos.

Next Steps

You’ve successfully connected GitHub Cloud to LinearB.

How did we do?

Integration Guide - Bitbucket (Cloud + Server)

Integration Guide - GitHub Enterprise Server (on-prem)

Contact