How to Setup gitStream with GitLab

GitLab Installation Overview

1. Designate a gitStream user account.
2. Create a CM configuration file.
3. Create a GitLab pipeline.
4. Install the gitStream service.

Designate a gitStream User Account

gitStream automation rules are executed on behalf of the user account configured when you install the gitStream service. This account must have the maintainer or owner role to the relevant repos.

We recommend creating a dedicated service account to control access to individual repos easily. You can also use your professional or personal GitLab account for this, which would result in all automations being executed under that account, which might also affect LinearB's metrics.

Create a cm repo and a CM Configuration File

Group rules are ideal when you want to enforce consistent rules across every repo in your GitLab group. You can define them by creating a special repository named cm in the parent group for the git repositories on which you want to run gitStream. Here, you can add automation files that apply to all repositories within that group that are connected to gitStream.

Create a cm project (repository) in your GitLab group, and 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 the CM file anything you want as long as it ends in .cm

# -*- 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:
  # 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'

Create a GitLab Pipeline

Once your gitStream configuration file is set up, you need a GitLab CI configuration file to trigger gitStream automations. Create a cm project (repository) in your GitLab group if you haven't already. It should be created in the same group or a parent group of the target repositories. Create a .gitlab-ci.yml file in your new cm repository's default branch (usually master or main) and add the following configuration:

# Code generated by gitStream - DO NOT EDIT
gitstream-job:
  stage: gitstream-main
  image: gitstream/rules-engine:latest
  only:
    variables:
      - $GITSTREAM_MAIN_JOB
  except:
    variables:
      - $GITSTREAM_BLOCK_MERGE
  script:
    - apk update && apk add git
    - mkdir /code
    - git clone https://gitlab-ci-token:${CI_JOB_TOKEN}${repoUrl} /code/repo
    - git clone https://gitlab-ci-token:${CI_JOB_TOKEN}${cmUrl} /code/cm
    - cd /code && cd repo && git fetch --all && git checkout $base_ref && git pull && ls && git checkout $head_ref && git pull && ls
    - |
      HEAD_REF=$head_ref BASE_REF=$base_ref CLIENT_PAYLOAD="$client_payload" RULES_RESOLVER_URL=$resolver_url \
      RULES_RESOLVER_TOKEN=$resolver_token  DEBUG_MODE=true npm run start

# Code generated by gitStream - DO NOT EDIT
stages:
  - gitstream-main
image: docker:latest
services:
  - docker:dind
before_script:
  - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY

gitstream-job:
  stage: gitstream-main
  tags:
    - REGISTERED-TAG
  only:
    variables:
      - $GITSTREAM_MAIN_JOB
  except:
    variables:
      - $GITSTREAM_BLOCK_MERGE
  script:
    - apk update && apk add git && apk add docker
    - git clone https://gitlab-ci-token:${CI_JOB_TOKEN}${repoUrl} gitstream/repo
    - git clone https://gitlab-ci-token:${CI_JOB_TOKEN}${cmUrl} gitstream/cm
    - cd gitstream && cd repo && git fetch --all && git checkout $base_ref && git pull && ls && git checkout $head_ref && git pull && ls
    - docker pull gitstream/rules-engine:latest
    - |
      docker run -v $CI_PROJECT_DIR/gitstream:/code \
      -e HEAD_REF=$head_ref \
      -e BASE_REF=$base_ref \
      -e CLIENT_PAYLOAD="$client_payload" \
      -e RULES_RESOLVER_URL=$resolver_url \
      -e RULES_RESOLVER_TOKEN=$resolver_token \
      -e DEBUG_MODE=true  gitstream/rules-engine:latest

script:
- ...
- docker pull YOUR-REGISTRY-URL/gitstream/rules-engine:latest

Next Step

If you successfully complete these instructions, 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.

When a suggest-reviewers label is applied to a PR, gitStream will comment with a list of code experts.

Additional Resources

Required GitLab Permissions

The required permissions are: