Skip to content

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 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@v1
        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@v1
        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 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

To ensure gitStream runs on self-hosted GitHub Actions runners, follow these steps to configure it:

  1. Configure Self-Hosted Runners with Ensure you have self-hosted runners set up for your GitHub organization or repository. Refer to the GitHub documentation on self-hosted runners and Using self-hosted runners in a workflow for detailed instructions.

  2. Install Docker and Git on Self-Hosted Runners Make sure your self-hosted runners have Docker and Git installed. These are essential dependencies for gitStream to function properly. You can follow the official installation guides for Docker and Git.

  3. Update GitHub Actions Configuration Open the gitStream GitHub Actions workflow file (.github/workflows/gitstream.yml) and update the runs-on field to specify that the gitStream job must run on self-hosted runners. For example:

    jobs:
  gitStream:
    runs-on: self-hosted
    # ... other configuration ...

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

  5. Test with a Sample PR Create a sample pull request and observe gitStream's behavior. It will use the configured self-hosted runners.

Caching the Docker Image Using GitHub Cache

gitStream provides an optional method to control the frequency of Docker image downloads per day using GitHub's cache services, helping to manage build resources efficiently. By using the update_times_a_day argument, you can specify the number of times the Docker image should be downloaded and cached daily. If this argument is not specified, no caching will occur.

Configure Docker Image Caching

Add the update_times_a_day parameter to the Evaluate Rules step of your gitStream GitHub Actions workflow.

  • Open Your GitHub Actions Workflow File and Modify the Evaluate Rules Step: Navigate to your .github/workflows directory, open gitStream's workflow yml, and update the Evaluate Rules step. Add the update_times_a_day parameter to set the exact times the Docker image is downloaded and cached daily.

  • Example Configuration: Here is how you might configure the caching within your workflow:

    steps:
  - name: Evaluate Rules
    uses: linear-b/gitstream-github-action@v1
    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 }}
      update_times_a_day: 6

    In this example, the Docker image is set to be downloaded and cached six times a day, distributed evenly across 24 hours (i.e., the image will be downloaded every 4 hours). This parameter can be adjusted to fit your workflow needs and resource management strategies. Without specifying this argument, no caching will be performed.

Uninstalling gitStream

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