Skip to content

How to Setup gitStream with GitLab

Prerequisites

  1. GitLab cloud
  2. GitLab runner v15 or higher

Tip

gitStream automation rules are executed on behalf of the user account used to install it, and this account must have the Maintainer role. We recommend creating a new dedicated account (e.g. gitstream-cm) in GitLab to install the gitStream app.

Setup

You can set up gitStream for a single repo or your entire GitLab 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 GitLab repo. The first is a configuration file that defines the workflow automations to execute for the repo. The second is a GitLab actions configuration file that triggers gitStream when PRs are created or updated which is hosted in a special cm repo.

Prerequisite: Create a cm repo and enable gitStream.

Create a cm project (repository) in your GitLab group. It should be created in the same group or a parent group of the target repositories

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/quick-start/
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
      # etr is defined in the last section of this example
        args:
          label: "{{ calc.etr }} min review"
          color: {{ 'E94637' if (calc.etr >= 20) else ('FBBD10' if (calc.etr >= 5) else '36A853') }}
  # Post a comment that lists the best experts for the files that were modified.
  suggest_code_experts:
    # Triggered when someone applies a suggest-reviewer label to a PR.
    if: 
      - {{ pr.labels | match(term='suggest-reviewer') }}
    # Identify the best experts to assign for review and post a comment that explains why
    # More info about code experts
    # https://docs.gitstream.cm/filter-functions/#codeexperts
    run:
      - action: add-comment@v1
        args:
          comment: |
            {{ repo | explainCodeExperts(gt=10) }}
# The next function calculates the estimated time to review and makes it available in the automation above.
calc:
  etr: {{ branch | estimatedReviewTime }}

GitLab CI

Once your gitStream configuration file is setup, you need a GitLab CI configuration file to trigger gitStream automations. Create a new cm project (repository) in your GitLab group. 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
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
  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

Success

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

.
├─ .gitlab-ci.yml

And in your target repository:

.
├─ .cm/
│  └─ gitstream.cm

GitLab Group 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 GitLab organization top group where you can add automation files that will apply to all repositories within that organization.

Prerequisite: Create a cm repo and enable gitStream.

Create a cm project (repository) in your GitLab group. It should be created in the same group or a parent group of the target repositories

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/quick-start/
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
      # etr is defined in the last section of this example
        args:
          label: "{{ calc.etr }} min review"
          color: {{ 'E94637' if (calc.etr >= 20) else ('FBBD10' if (calc.etr >= 5) else '36A853') }}
  # Post a comment that lists the best experts for the files that were modified.
  suggest_code_experts:
    # Triggered when someone applies a suggest-reviewer label to a PR.
    if: 
      - {{ pr.labels | match(term='suggest-reviewer') }}
    # Identify the best experts to assign for review and post a comment that explains why
    # More info about code experts
    # https://docs.gitstream.cm/filter-functions/#codeexperts
    run:
      - action: add-comment@v1
        args:
          comment: |
            {{ repo | explainCodeExperts(gt=10) }}
# The next function calculates the estimated time to review and makes it available in the automation above.
calc:
  etr: {{ branch | estimatedReviewTime }}
GitLab CI

Once your gitStream configuration file is setup, you need a GitLab CI configuration file to trigger gitStream automations. 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
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
  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

Success

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

.
├─ .gitlab-ci.yml
├─ gitstream.cm

Install gitStream App

Install gitStream

The last step of the process is to install the gitStream app to your GitLab organization.

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

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

Attention

When renaming or adding new repositories, you must re-authenticate gitStream in GitLab

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 GitLab Permissions

The required permissions are:

Permissions Reason
Read/Write API To get notified on MR changes and allow gitStream to approve MRs once all conditions are met
Read repository To read and check rules over the code changes on monitored repositories
Read user profile Used to identify users

No support for gitStream to Block Merges

gitStream actions that blocks MR merge are not support at the moment.

gitStream service account

Automation rules by gitStream are executed on behalf of the user account used to install it. We recommend using a new dedicated account in GitLab for installing gitStream, e.g. gitstream-cm

Uninstalling gitStream

Use the following link to uninstall gitStream app for GitLab.

Attention

The uninstalling account has to have at least Developer or Maintainer role in the Group.