Custom GitHub App for Self-Hosted GitHub Server

A GitHub application serves as the link between gitStream and GitHub. It facilitates user authentication via OAuth2 and allows users to select repositories accessible by gitStream.

In this section, we'll guide you through creating a GitHub app for your self-hosted gitStream installation. By the end, you should have noted down the following values:

• App ID
• Private Key

1. Connect GitHub Server to LinearB

First login, or create a free account on the LinearB app.

In LinearB, go to Settings -> Git -> click the Connect gitStream button next to your GitHub Server integration. You’ll need to use the Webhook URL and Webhook secret later when setting up the GitHub App.

Keep this window open and complete the next steps in GitHub. Once you have the App ID and Private Key (.pem file), you can complete the connection in LinearB.

2. Create a New GitHub App

Any GitHub account can own the app, but we recommend creating it under the organization account of the team who will maintain the gitStream installation.

• Log in to GitHub and go to your organization account page (e.g., https://github.com/<organization account name>)
• Click on Settings -> Developer Settings -> GitHub Apps -> New GitHub App as shown below
• Or go directly to https://github.com/organizations/<organization account name>/settings/apps/new

3. Set Up URLs and General Information

Fill in the app information as shown in the screenshot below. For URLs, replace gitstream.<your-domain>.com with the actual endpoint at which you'll be hosting the gitStream application.

4. Set Up Permissions

We need the following permissions to enable all gitStream functionality:

• Write access to dedicated gitStream app files: Used to set up the gitStream workflow files
• Write access to code: To allow gitStream to approve PRs once all conditions are met
• Read access to administration, issues, and metadata: To get user team membership and branch protection settings
• Read and write access to actions, checks, pull requests, and workflows: Trigger workflows, create and update pull requests and their checks, and modify workflow files
• User email: Used to identify users |

You need to enable these under the permissions section as shown below:

5. Webhook Events and Scope

• Subscribe to events so gitStream is notified when a PR is created, changed, or commented on, etc

6. Generate a Private Key

Once the app is created, scroll down and click Generate private key. This will create and download a .pem file for you.

7. Upload a Logo

Download the logo file and upload the logo to your app.

• Black logo
• White logo

8. Get App Configuration

On your newly created app page, you can find the App ID.

9. Finish Setup in LinearB

To complete the integration, fill in the App ID and Private Key in the LinearB setup screen.

10. Connect GitHub App to Your Repositories

Go to your organization settings in GitHub and in Third-party Access choose the GitHub Apps. You may need to choose the account to install the gitStream app on. Choose your org you used to create the GitHub app in the previous sections.

Choose the repositories you want to connect.

11. Finish Setting Up gitStream

Follow the instructions to configure your repository using the GitHub Instructions