How to Setup gitStream with GitLab
Prerequisites
- GitLab cloud
- GitLab runner v15 or higher
- Login, or create a free account on the LinearB app, and follow the steps to connect gitStream Using a GitLab Integration.
GitLab Installation Overview
- Designate a gitStream user account.
- Create a CM configuration file.
- Create a GitLab pipeline.
- 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.
Use this account when you install gitStream
Make sure you're logged into this user account in the web browser that you use to click the installation button in step 4.
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.
Single Repo Setup
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
Example Configuration
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.
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 }}
GitLab Group Setup
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 you want to run gitStream on. Here, you can add automation files that will apply to all repositories within that group.
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
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.
Example Configuration
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.
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.
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 |
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.
Warning
The uninstalling account has to have at least Developer
or Maintainer
role in the Group.
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.