Note

This guide is for installations on self-hosted GitHub Server. If you are using the gitStream cloud service, please refer to this guide.

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.

Prerequisites

GitHub Server v3.10 or higher
Allowed network connection between the server and the following IPs:
- 13.56.203.235
- 54.151.81.98

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

Note

Throughout this document, when we refer to a GitHub account, it refers to your own GitHub Server installation.

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.

LinearB setup

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 on your self-hosted GitHub Server 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 your GitHub Server and go to your organization account page (e.g., https://<GITHUB_SERVER_URL>/<organization account name>)
Navigate to Settings -> Developer Settings -> GitHub Apps -> New GitHub App as shown below
Or go directly to https://<GITHUB_SERVER_URL>/settings/apps

GitHub App Creation

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.

Warning

Do not forget trailing slashes for the URLs
Do not forget to disable the "Expire user authorization tokens" checkbox
The GitHub App name must contain gitstream in lower case

Tip

Use the following texts:

GitHub App name: gitstream app
Homepage URL: https://gitstream.cm

GitHub App Setup - Register

Tip

Use the following texts:

Webhook URL from LinearB setup page
Webhook secret from LinearB setup page

GitHub App Setup - Post Installation

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:

Permissions Setup 1

Tip

Add the following Path (content paths to single files the app can access):

.cm/gitstream.cm
.github/workflows/gitstream.yml

Permissions Setup 2 Permissions Setup 3 Permissions Setup 4

5. Webhook Events and Scope

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

Permissions Setup 5 Permissions Setup 6

Tip

"Where can this GitHub App be installed?" choose "Any account" so other orgs in your company can use gitStream as well. For on-prem installations that work with github.com, only repositories under your company's org account can be accessed via gitStream.

Permissions Setup 7

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.

Tip

Please keep this file safe, we'll need to put it back in LinearB setup.

Private Key

7. Upload a Logo

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

8. Get App Configuration

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

Tip

Please keep the App ID, we'll need to put it back in LinearB setup.

App Config Details

9. Finish Setup in LinearB

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

Tip

Use the App ID, and Private key (.pem file) to complete the LinearB setup.

LinearB setup

10. Connect GitHub App to Your Repositories

Go to your organization settings in GitHub and navigate to Third-party Access to manage GitHub Apps. Select the account where you want to install the gitStream app. Choose the organization you used to create the GitHub app in the previous steps.

Alternatively, you can go directly to the app settings at https://<GITHUB_SERVER_URL>/settings/apps/<gitstream-app>/installations and add the app to the relevant organizations.

GitHub app setup

Choose the repositories you want to connect.

Tip

It's recommended to select All repositories, as it covers also future repositories.

Repository access

11. Finish Setting Up gitStream

You can now set up gitStream for a single repo, your GitHub organization or across all the organizations in the server. Select the tab below for the instructions you want.

Single RepoGitHub OrganizationGitHub Multi Org

Single Repo Setup

You must implement two main components for gitStream to function for a single GitHub repo. The first is a configuration file that defines the workflow automations to execute for the repo. The second is a GitHub actions configuration file that triggers gitStream when PRs are created or updated.

Required Configurations

gitStream

Create a .cm/gitstream.cm rules file in your repository's default branch (usually master or main). This file will contain a YAML configuration that determines the workflows that run on the repo, and you can name it anything you want as long as it ends in .cm

Here is an example of a gitStream configuration file you can use to setup some basic workflow automations.

# -*- mode: yaml -*-
# This example configuration provides basic automations to get started with gitStream.
# View the gitStream quickstart for more examples: https://docs.gitstream.cm/examples/
manifest:
  version: 1.0


automations:
  # Use LinearB's AI service to review the changes
  linearb_ai_review:
    on:
      - pr_created
      - commit
    if:
      - {{ not pr.draft }}
      - {{ pr.author | match(list=['github-actions', 'dependabot', '[bot]']) | nope }}
    run:
      - action: code-review@v1

  # Use LinearB's AI service to add a description to the PR
  linearb_ai_description:
    on:
      - pr_created
      - commit
    if:
      - {{ not pr.draft }}
      - {{ pr.author | match(list=['github-actions', 'dependabot', '[bot]']) | nope }}
    run:
      - action: describe-changes@v1
        args:
          concat_mode: append

  # Add a label indicating how long it will take to review the PR.
  estimated_time_to_review:
    if:
      - true
    run:
      - action: add-label@v1
        args:
          label: "{{ calc.etr }} min review"
          color: {{ colors.red if (calc.etr >= 20) else ( colors.yellow if (calc.etr >= 5) else colors.green ) }}
  # Inform PR authors when they fail to reference Jira tickets in the PR title or description.
  label_missing_jira_info:
    if:
      - {{ not (has.jira_ticket_in_title or has.jira_ticket_in_desc) }}
    run:
      - action: add-label@v1
        args:
          label: "missing-jira"
          color: {{ colors.red }}
      - action: add-comment@v1
        args:
          comment: |
            This PR is missing a Jira ticket reference in the title or description.
            Please add a Jira ticket reference to the title or description of this PR.
  # Post a comment that lists the best experts for the files that were modified.
  explain_code_experts:
    if:
      - true
    run:
      - action: explain-code-experts@v1 
        args:
          gt: 10 


# +----------------------------------------------------------------------------+
# | Custom Expressions                                                         |
# | https://docs.gitstream.cm/how-it-works/#custom-expressions                 |
# +----------------------------------------------------------------------------+

calc:
  etr: {{ branch | estimatedReviewTime }}

has:
  jira_ticket_in_title: {{ pr.title | includes(regex=r/\b[A-Za-z]+-\d+\b/) }}
  jira_ticket_in_desc: {{ pr.description | includes(regex=r/atlassian.net\/browse\/\w{1,}-\d{3,4}/) }}

colors:
  red: 'b60205'
  yellow: 'fbca04'
  green: '0e8a16'

GitHub Actions Once your gitStream configuration file is setup, you need a Github Actions configuration file to trigger gitStream automations. Create a .github/workflows/gitstream.yml file in your repository's default branch (usually master or main) and add the following configuration:

# Code generated by gitStream GitHub app - DO NOT EDIT

name: gitStream workflow automation
run-name: |
  /:\ gitStream: PR #${{ fromJSON(fromJSON(github.event.inputs.client_payload)).pullRequestNumber }} from ${{ github.event.inputs.full_repository }}

on:
  workflow_dispatch:
    inputs:
      client_payload:
        description: The Client payload
        required: true
      full_repository:
        description: the repository name include the owner in `owner/repo_name` format
        required: true
      head_ref:
        description: the head sha
        required: true
      base_ref:
        description: the base ref 
        required: true
      installation_id:
        description: the installation id
        required: false
      resolver_url:
        description: the resolver url to pass results to
        required: true
      resolver_token:
        description: Optional resolver token for resolver service
        required: false
        default: ''

jobs:
  gitStream:
    timeout-minutes: 15
    runs-on: ubuntu-latest
    name: gitStream workflow automation
    steps:
      - name: Evaluate Rules
        uses: linear-b/gitstream-github-action@v2
        id: rules-engine
        with:
          full_repository: ${{ github.event.inputs.full_repository }}
          head_ref: ${{ github.event.inputs.head_ref }}
          base_ref: ${{ github.event.inputs.base_ref }}
          client_payload: ${{ github.event.inputs.client_payload }}
          installation_id: ${{ github.event.inputs.installation_id }}
          resolver_url: ${{ github.event.inputs.resolver_url }}
          resolver_token: ${{ github.event.inputs.resolver_token }}

Success

When finished, you should have the following file structure in your repo.

.
├─ .cm/
│  └─ gitstream.cm
├─ .github/
│  └─ workflows/
│     └─ gitstream.yml

GitHub Organization Setup

Organization rules are ideal when you want to enforce consistent rules across every repo in your organization. You can define them by creating a special repository named cm in your GitHub organization where you can add automation files that will apply to all repositories within that organization.

Prerequisite: Create a cm repo and enable gitStream.

Organization-wide automations need to be defined in a repo named "cm" inside your GitHub organization. Before continuing, you must create this repo and enable the gitStream app for it.

Required Configurations

gitStream

Create a gitstream.cm rules file in the root directory of your cm repository's default branch (usually master or main). This file will contain a YAML configuration that determines the workflows that run on your organization's repos. You can name it anything you want as long as it ends in .cm

Configuration files go in the repo's root directory.

Unlike the set up instructions for a single repo, your .cm files should be placed in the repository's root directory.

# -*- mode: yaml -*-
# This example configuration provides basic automations to get started with gitStream.
# View the gitStream quickstart for more examples: https://docs.gitstream.cm/examples/
manifest:
  version: 1.0


automations:
  # Use LinearB's AI service to review the changes
  linearb_ai_review:
    on:
      - pr_created
      - commit
    if:
      - {{ not pr.draft }}
      - {{ pr.author | match(list=['github-actions', 'dependabot', '[bot]']) | nope }}
    run:
      - action: code-review@v1

  # Use LinearB's AI service to add a description to the PR
  linearb_ai_description:
    on:
      - pr_created
      - commit
    if:
      - {{ not pr.draft }}
      - {{ pr.author | match(list=['github-actions', 'dependabot', '[bot]']) | nope }}
    run:
      - action: describe-changes@v1
        args:
          concat_mode: append

  # Add a label indicating how long it will take to review the PR.
  estimated_time_to_review:
    if:
      - true
    run:
      - action: add-label@v1
        args:
          label: "{{ calc.etr }} min review"
          color: {{ colors.red if (calc.etr >= 20) else ( colors.yellow if (calc.etr >= 5) else colors.green ) }}
  # Inform PR authors when they fail to reference Jira tickets in the PR title or description.
  label_missing_jira_info:
    if:
      - {{ not (has.jira_ticket_in_title or has.jira_ticket_in_desc) }}
    run:
      - action: add-label@v1
        args:
          label: "missing-jira"
          color: {{ colors.red }}
      - action: add-comment@v1
        args:
          comment: |
            This PR is missing a Jira ticket reference in the title or description.
            Please add a Jira ticket reference to the title or description of this PR.
  # Post a comment that lists the best experts for the files that were modified.
  explain_code_experts:
    if:
      - true
    run:
      - action: explain-code-experts@v1 
        args:
          gt: 10 


# +----------------------------------------------------------------------------+
# | Custom Expressions                                                         |
# | https://docs.gitstream.cm/how-it-works/#custom-expressions                 |
# +----------------------------------------------------------------------------+

calc:
  etr: {{ branch | estimatedReviewTime }}

has:
  jira_ticket_in_title: {{ pr.title | includes(regex=r/\b[A-Za-z]+-\d+\b/) }}
  jira_ticket_in_desc: {{ pr.description | includes(regex=r/atlassian.net\/browse\/\w{1,}-\d{3,4}/) }}

colors:
  red: 'b60205'
  yellow: 'fbca04'
  green: '0e8a16'

GitHub Actions

Once your gitStream configuration file is set up, you will need to create a Github Actions configuration file to trigger gitStream automations. Create a .github/workflows/gitstream.yml file in your cm repository's default branch (usually master or main) and add the following configuration:

# Code generated by gitStream GitHub app - DO NOT EDIT

name: gitStream workflow automation
run-name: |
  /:\ gitStream: PR #${{ fromJSON(fromJSON(github.event.inputs.client_payload)).pullRequestNumber }} from ${{ github.event.inputs.full_repository }}

on:
  workflow_dispatch:
    inputs:
      client_payload:
        description: The Client payload
        required: true
      full_repository:
        description: the repository name include the owner in `owner/repo_name` format
        required: true
      head_ref:
        description: the head sha
        required: true
      base_ref:
        description: the base ref 
        required: true
      installation_id:
        description: the installation id
        required: false
      resolver_url:
        description: the resolver url to pass results to
        required: true
      resolver_token:
        description: Optional resolver token for resolver service
        required: false
        default: ''

jobs:
  gitStream:
    timeout-minutes: 15
    runs-on: ubuntu-latest
    name: gitStream workflow automation
    steps:
      - name: Evaluate Rules
        uses: linear-b/gitstream-github-action@v2
        id: rules-engine
        with:
          full_repository: ${{ github.event.inputs.full_repository }}
          head_ref: ${{ github.event.inputs.head_ref }}
          base_ref: ${{ github.event.inputs.base_ref }}
          client_payload: ${{ github.event.inputs.client_payload }}
          installation_id: ${{ github.event.inputs.installation_id }}
          resolver_url: ${{ github.event.inputs.resolver_url }}
          resolver_token: ${{ github.event.inputs.resolver_token }}

Success

Once finished, all PRs to your organization's repositories will be processed by the GitHub Action in this repo, and your cm repo should have a file directory that looks like this.

``` . ├─ gitstream.cm ├─ .github/ │ └─ workflows/ │ └─ gitstream.yml

GitHub Multi Org Setup

Multi-org rules are ideal when you want to enforce consistent rules across every repo across multiple organizations on your server. You can define them by creating a special repository named cm under the cm organization in your GitHub Server where you can add automation files that will apply to all repositories across all organizations.

Prerequisite: Create a cm repo under the cm org and enable gitStream.

Multi-org automations need to be defined in a repo named cm inside the cm organization on your GitHub Server. Before continuing, you must create this repo and enable the gitStream app for it.

Required Configurations

gitStream

Create a gitstream.cm rules file in the root directory of the cm repository's default branch (usually master or main). This file will contain a YAML configuration that determines the workflows that run on your server's repos. You can name it anything you want as long as it ends in .cm

Configuration files go in the repo's root directory.

Unlike the setup instructions for a single repo, your .cm files should be placed in the repository's root directory.

# -*- mode: yaml -*-
# This example configuration provides basic automations to get started with gitStream.
# View the gitStream quickstart for more examples: https://docs.gitstream.cm/examples/
manifest:
  version: 1.0


automations:
  # Use LinearB's AI service to review the changes
  linearb_ai_review:
    on:
      - pr_created
      - commit
    if:
      - {{ not pr.draft }}
      - {{ pr.author | match(list=['github-actions', 'dependabot', '[bot]']) | nope }}
    run:
      - action: code-review@v1

  # Use LinearB's AI service to add a description to the PR
  linearb_ai_description:
    on:
      - pr_created
      - commit
    if:
      - {{ not pr.draft }}
      - {{ pr.author | match(list=['github-actions', 'dependabot', '[bot]']) | nope }}
    run:
      - action: describe-changes@v1
        args:
          concat_mode: append

  # Add a label indicating how long it will take to review the PR.
  estimated_time_to_review:
    if:
      - true
    run:
      - action: add-label@v1
        args:
          label: "{{ calc.etr }} min review"
          color: {{ colors.red if (calc.etr >= 20) else ( colors.yellow if (calc.etr >= 5) else colors.green ) }}
  # Inform PR authors when they fail to reference Jira tickets in the PR title or description.
  label_missing_jira_info:
    if:
      - {{ not (has.jira_ticket_in_title or has.jira_ticket_in_desc) }}
    run:
      - action: add-label@v1
        args:
          label: "missing-jira"
          color: {{ colors.red }}
      - action: add-comment@v1
        args:
          comment: |
            This PR is missing a Jira ticket reference in the title or description.
            Please add a Jira ticket reference to the title or description of this PR.
  # Post a comment that lists the best experts for the files that were modified.
  explain_code_experts:
    if:
      - true
    run:
      - action: explain-code-experts@v1 
        args:
          gt: 10 


# +----------------------------------------------------------------------------+
# | Custom Expressions                                                         |
# | https://docs.gitstream.cm/how-it-works/#custom-expressions                 |
# +----------------------------------------------------------------------------+

calc:
  etr: {{ branch | estimatedReviewTime }}

has:
  jira_ticket_in_title: {{ pr.title | includes(regex=r/\b[A-Za-z]+-\d+\b/) }}
  jira_ticket_in_desc: {{ pr.description | includes(regex=r/atlassian.net\/browse\/\w{1,}-\d{3,4}/) }}

colors:
  red: 'b60205'
  yellow: 'fbca04'
  green: '0e8a16'

GitHub Actions

Once your gitStream configuration file is set up, you will need to create a Github Actions configuration file to trigger gitStream automations. Create a .github/workflows/gitstream.yml file in your cm repository's default branch (usually master or main) and add the following configuration:

# Code generated by gitStream GitHub app - DO NOT EDIT

name: gitStream workflow automation
run-name: |
  /:\ gitStream: PR #${{ fromJSON(fromJSON(github.event.inputs.client_payload)).pullRequestNumber }} from ${{ github.event.inputs.full_repository }}

on:
  workflow_dispatch:
    inputs:
      client_payload:
        description: The Client payload
        required: true
      full_repository:
        description: the repository name include the owner in `owner/repo_name` format
        required: true
      head_ref:
        description: the head sha
        required: true
      base_ref:
        description: the base ref 
        required: true
      installation_id:
        description: the installation id
        required: false
      resolver_url:
        description: the resolver url to pass results to
        required: true
      resolver_token:
        description: Optional resolver token for resolver service
        required: false
        default: ''

jobs:
  gitStream:
    timeout-minutes: 15
    runs-on: ubuntu-latest
    name: gitStream workflow automation
    steps:
      - name: Evaluate Rules
        uses: linear-b/gitstream-github-action@v2
        id: rules-engine
        with:
          full_repository: ${{ github.event.inputs.full_repository }}
          head_ref: ${{ github.event.inputs.head_ref }}
          base_ref: ${{ github.event.inputs.base_ref }}
          client_payload: ${{ github.event.inputs.client_payload }}
          installation_id: ${{ github.event.inputs.installation_id }}
          resolver_url: ${{ github.event.inputs.resolver_url }}
          resolver_token: ${{ github.event.inputs.resolver_token }}

Success

Once finished, all PRs to repositories across all organizations on your server will be processed by the GitHub Action in this repo, and your cm repo should have a file directory that looks like this.

.
├─ gitstream.cm
├─ .github/
│  └─ workflows/
│     └─ gitstream.yml