Connect to GitHub

OAuth access is our preferred method of connecting to GitHub. We recommend using this method unless permission issues prevent it. In that situation, we recommend using a Personal Access Token (PAT) as outlined below.

Connecting to GitHub via OAuth

Navigate to your company settings, and select Git. From there, select the option to add a new integration, and select GitHub. You will be presented with an option to authorize via OAuth or a PAT; select the "Authorize GitHub" button on the left. From there, you will be presented with an option to Connect GitHub:

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.

Connecting to GitHub via PAT

In situations where you are not an admin of your GitHub org, or otherwise do not have the necessary permissions to authenticate your GitHub account with LinearB via OAuth, you can still connect by using GitHub personal access tokens.

Create a personal access token in GitHub

GitHub describes how to create a personal access token within your GitHub user account. Click here to learn how to create a personal access token in GitHub

Set your Expiration Date

It's advisable to set an expiration date long into the future, or if possible set no expiration date. If a GitHub token expires, there is a potential for data inconsistencies in the gap of time between when the token expires and a new token is added. In these instances please contact support@linearb.io to assist in validating and correcting any data issues.

Grant the correct permissions

The personal access token will need the following options selected:

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

What if I don't/can't grant write:repo-hook permissions?

The only write permission LinearB asks for is on webhooks. LinearB uses this to connect a webhook to your repo and gather data into the LinearB app in real-time. This permission can be excluded from your token if your organization has security restrictions, however, data collected by LinearB will only update every 2 hours. This can cause confusion in reviewing metrics, and also will cause long delays in WorkerB notifications for time-sensitive matters such as PR review requests.

A second option to using the token-level repo-hook permissions would be installing an org-level webhook. You can read more about installing org-level webhooks here: Installing a GitHub Organization-Level Webhook

Add your GitHub token to LinearB

Once generated, paste your personal access token into LinearB's connect page. If you have not yet connected a Git account, you will be directed to this page upon logging in. If you have already connected a GitHub account, click on the gear icon in the top right of your page, select Company Settings, click on the Git tab, and click the Add Integration button. Paste in your token and LinearB will begin processing your GitHub data!

Reauthorizing a GitHub PAT with LinearB

To reauthorize an expired GitHub token, please generate a new token using the instructions above, go to Company Settings -> Git and click on the three dots next to your existing GitHub token connection. Select reauthorize Git and add your new Token ID.

If you have any additional questions don't hesitate to reach out to us via email. You can also chat about anything Git or dev related if you join our Dev Interrupted Discord server!