How to Setup gitStream with GitHub

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 RepoGitHub Organization

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 for 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:
  # Add a label that indicates how many minutes 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: 5
    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 for 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:
  # Add a label that indicates how many minutes 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: 5
    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

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](screenshots/etr_label_example.png)
![Estimated review time](screenshots/slack-estimated-review-time-example-1-min.png)

When a new PR is created, comment with a list of code experts.
![Suggested reviewers](screenshots/github-codeexperts-expanded.png)

Next Step

How gitStream Works

Read our guide: [How gitStream Works](/how-it-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.

Go to repo settings
On the left panel select Code and automation > Branches
Set Branch protection rules for your desired branch
Enable Require status checks to pass before merging
Search for status checks in the last week for this repository
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:

Configure Self-Hosted Runners
- Set up self-hosted runners for your GitHub organization or repository. Refer to GitHub documentation on self-hosted runners and using them in a workflow for detailed instructions.
Prerequisites for Self-Hosted Runners
- Git: Installation instructions can be found here.
- Python 3.x
  - black 24.4.2
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 ...
```
Save and Commit
- Save changes to the workflow file and commit them to your repository.
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"