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.

1. Designate a gitStream User Account

gitStream automation rules are executed on behalf of the user account that is logged in when you install the gitStream service. This account must have the Maintainer role.

We recommend creating a dedicated account for this purpose so you can more easily control access to individual repos. You can also use your professional or personal GitLab account for this, but that would result in all automations being executed under that account.

2. Create a CM Configuration File

You can set up gitStream for a single repo or your entire GitLab organization. Select the tab below for the instructions you want.

# -*- 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.
  explain_code_experts:
    if:
      - true
    run:
      - action: explain-code-experts@v1 
        args:
          gt: 10 
# The next function calculates the estimated time to review and makes it available in the automation above.
calc:
  etr: {{ branch | estimatedReviewTime }}

# -*- 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.
  explain_code_experts:
    if:
      - true
    run:
      - action: explain-code-experts@v1 
        args:
          gt: 10 
# The next function calculates the estimated time to review and makes it available in the automation above.
calc:
  etr: {{ branch | estimatedReviewTime }}

3. Create a GitLab Pipeline

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

Next Step

If you successfully completed 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:

FAQ

Does gitStream support the ability to block merges?"

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

How do I uninstall gitStream?

Use the following link to uninstall gitStream app for GitLab.

What is a gitStream service account?

gitStream executes rules on behalf of the user account that was used to install it. We recommend using a new dedicated account in GitLab for installing gitStream.