Skip to content

How to Setup gitStream with GitLab

Prerequisites

  1. GitLab
  2. GitLab runner v15 or higher with ability to run apk commands
  3. Login, or create a free account on the LinearB app, and follow the steps to connect gitStream Using a GitLab Integration.

GitLab Installation Overview

  1. Designate a gitStream user account.
  2. Create a cm repo and .cm configuration file.
  3. Create a GitLab pipeline.
  4. Connect gitStream in LinearB.

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.

Use this account when you integrate gitStream

Make sure to use this account when authorizing GitLab in LinearB.

Create a cm repo and .cm configuration file.

Create a cm project (repository) in your GitLab group. This repository must be created in the same group or parent group as the target repositories. In the root directory of the default branch (usually master or main), create a gitstream.cm rules file to define the workflow automations. The file name can vary but must end in .cm.

Configuration File Locations

Group-level rules require your .cm files to be placed in the cm repository's root directory. You can also define specific repo-level rules under the .cm folder in each of the connected repositories.

Example Configuration

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

Gitlab-Hosted Runners

Use the following .gitlab-ci.yml

# 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

Self-Managed Runners

First, register the runner with a tag, and use the named tag in the .gitlab-ci.yml file

Shell executors

Use the tag created above in the workflow file cm/.gitlab-ci.yml instead REGISTERED-TAG

# 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

Self-Managed Runners

First, register the runner with a tag, and use the named tag in the .gitlab-ci.yml file

Kubernetes executors

  1. Ensure your runner configuration (config.toml for example) has the followig:
    [runners.kubernetes]
    privileged = true
    
  2. Use the tag created above in the workflow file cm/.gitlab-ci.yml instead REGISTERED-TAG
    # Code generated by gitStream - DO NOT EDIT
    variables:
      DOCKER_DRIVER: overlay2
      DOCKER_HOST: tcp://docker:2375
      DOCKER_TLS_CERTDIR: ""
    stages:
      - gitstream-main
    
    image: docker:latest
    services:
      - name: docker:dind
        command: ["--mtu=1450", "--tls=false"]
    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
    

Configuring the image location

By default, gitStream pulls the image from DockerHub each time it is invoked. You can configure gitStream to pull the docker image from your own registry, to allow faster build times and reduced bandwidth usage - especially for teams with high CI/CD throughput, by downloading the image and storing it in your own registry (ECR or K8S registry, for example) and changing the cm/.gitlab-ci.yml accordingly:

script:
- ...
- docker pull YOUR-REGISTRY-URL/gitstream/rules-engine:latest
The docker image can be pulled to your private repository from DockerHub.

Connect gitStream in LinearB

To complete the setup, connect gitStream in LinearB. Follow the instructions in the LinearB app to connect your GitLab account and repositories to gitStream.

Next Step

If you complete these instructions, gitStream will now automate your Merge Request workflows on GitLab.

How gitStream Works

Read our guide, How gitStream Works, for a deeper understanding of gitStream's capabilities and how to leverage them fully.

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