Skip to content

How to Setup gitStream with GitHub

Prerequisites

Allowed network connection between the runners and the following IPs:

  • 13.56.203.235
  • 54.151.81.98
Understanding IP Allowlisting for gitStream

When setting up IP allowlists in GitHub, you're specifying which source IP addresses are permitted to interact with your repositories and APIs. This affects both gitStream and your CI/CD runners.

There are two primary cases where this matters for gitStream:

  1. Webhook Event Handling by gitStream When GitHub triggers a webhook event (e.g., a pull request opened), gitStream may need to make follow-up API calls to GitHub. This can include fetching additional metadata, posting comments to the PR, or performing other actions. These calls are made from the LinearB/gitStream service, which uses a fixed set of IP addresses. These IPs must be added to your GitHub allowlist to ensure proper operation.
  2. Outbound Requests from Your CI Runner When your pipeline runs gitStream (e.g., via a GitHub Action), that runner might also make outbound calls to GitHub—for example, to clone a repository or retrieve commit history. These requests will originate from the runner's IP address.

If you encounter errors due to blocked IPs during your CI runs, it's likely that the runner is using an IP that is not part of the configured allowlist. This is a common issue with GitHub-hosted runners, as their IPs can be dynamic and change frequently.

Recommended Solution To ensure reliability:

  • Add LinearB/gitStream service IPs to your GitHub allowlist (listed above).
  • Use self-hosted runners or runners with static IPs so you can manage and allowlist their addresses explicitly.

This combination ensures that both gitStream's internal operations and your CI runners' interactions with GitHub function without network restrictions.

Install gitStream

Before you can complete the gitStream setup process, you need to install the gitStream app to your GitHub organization.

Setup

You can set up gitStream for a single repo or your entire GitHub organization. Select the tab below for the instructions you want.

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 }}
      - {{ not is.bot }}
    run:
      - action: code-review@v1
        args:
          approve_on_LGTM: {{ calc.safe_changes }}

  # Use LinearB's AI service to add a description to the PR
  linearb_ai_description:
    on:
      - pr_created
      - commit
    if:
      - {{ not pr.draft }}
      - {{ not is.bot }}
    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:
    on:
      - pr_created
      - pr_ready_for_review
      - commit
    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 }}
  safe_changes: {{ is.formatting or is.docs or is.tests or is.image }}

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'

is:
  formatting: {{ source.diff.files | isFormattingChange }}
  docs: {{ files | allDocs }}
  tests: {{ files | allTests }}
  image: {{ files | allImages }}
  bot: {{ pr.author | match(list=['github-actions', '_bot_', '[bot]', 'dependabot']) | some }}

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 }}

Download gitstream.yml (regular version) Download gitstream.yml (lite version)

Large Repository Support (Lite Version)

If you're working with a large repository (typically monorepos) and experience timeout issues during GitHub Actions execution, you can use the lite version of gitStream that performs a shallow clone to reduce execution time:

jobs:
  gitStream:
    timeout-minutes: 15
    runs-on: ubuntu-latest
    name: gitStream workflow automation
    steps:
      - name: Evaluate Rules
        uses: linear-b/gitstream-github-action@v2-lite
        id: rules-engine

Important: The lite version has limitations - automations that rely on Git history (such as code-experts) may not work properly due to the shallow clone.

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 }}
      - {{ not is.bot }}
    run:
      - action: code-review@v1
        args:
          approve_on_LGTM: {{ calc.safe_changes }}

  # Use LinearB's AI service to add a description to the PR
  linearb_ai_description:
    on:
      - pr_created
      - commit
    if:
      - {{ not pr.draft }}
      - {{ not is.bot }}
    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:
    on:
      - pr_created
      - pr_ready_for_review
      - commit
    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 }}
  safe_changes: {{ is.formatting or is.docs or is.tests or is.image }}

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'

is:
  formatting: {{ source.diff.files | isFormattingChange }}
  docs: {{ files | allDocs }}
  tests: {{ files | allTests }}
  image: {{ files | allImages }}
  bot: {{ pr.author | match(list=['github-actions', '_bot_', '[bot]', 'dependabot']) | some }}
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 }}

Download gitstream.yml (regular version) Download gitstream.yml (lite version)

Large Repository Support (Lite Version)

If you're working with large repositories in your organization (typically monorepos) and experience timeout issues during GitHub Actions execution, you can use the lite version of gitStream that performs a shallow clone to reduce execution time:

jobs:
  gitStream:
    timeout-minutes: 15
    runs-on: ubuntu-latest
    name: gitStream workflow automation
    steps:
      - name: Evaluate Rules
        uses: linear-b/gitstream-github-action@v2-lite
        id: rules-engine

Important: The lite version has limitations - automations that rely on Git history (such as code-experts) may not work properly due to the shallow clone. See the troubleshooting section for more details.

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

gitStream will now do these two things.

When a PR is created or changed, apply or update a label that provides an estimated time to review. Estimated Review Time label Estimated review time When a new PR is created, comment with a list of code experts. Suggested reviewers

Next Step

How gitStream Works

Read our guide: How gitStream Works to get an overview of the gitStream syntax and automation lifecycle.

Additional Resources

Required GitHub Permissions

Permissions Reason
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 the 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

Configure gitStream to Block Merges

You can configure Github to require gitStream checks to pass before PRs can be merged using branch protection rules.

Run a gitStream check before continuing

You need to run a check using your gitStream configuration at least once before it can be set as a required check. Make sure to open at least 1 PR before doing this setting.

Here are the steps to configure gitStream in your repo's branch protection rules.

  1. Go to repo settings
  2. On the left panel select Code and automation > Branches
  3. Set Branch protection rules for your desired branch
  4. Enable Require status checks to pass before merging
  5. Search for status checks in the last week for this repository
  6. Select gitStream.cm as required check

Branch protection rules

Required checks

Configuring gitStream with Self-Hosted Runners

Follow these steps to ensure gitStream runs on self-hosted GitHub Actions runners:

  1. Configure Self-Hosted Runners

  2. Prerequisites for Self-Hosted Runners

    • Git: Installation instructions can be found here.
    • Python 3.x
      • black 24.4.2

  3. Update GitHub Actions Configuration

    • Modify the gitStream GitHub Actions workflow file (.github/workflows/gitstream.yml) to specify self-hosted runners:
    jobs:
  gitStream:
    runs-on: self-hosted
    # ... other configuration ...

  4. Save and Commit

    • Save changes to the workflow file and commit them to your repository.

  5. Test with a Sample PR

    • Create a sample pull request to verify gitStream's behavior with self-hosted runners.

Uninstalling gitStream

Configure in your GitHub organization, and choose Uninstall "gitStream.cm"