How to Setup gitStream with GitLab
Prerequisites
- GitLab
- GitLab runner v15 or higher with ability to run apk commands
- Login, or create a free account on the LinearB app, and follow the steps to connect gitStream Using a GitLab Integration.
- Allowed network connection between the executors and the following IPs:
- 13.56.203.235
- 54.151.81.98
Understanding IP Allowlisting for gitStream
When setting up IP allowlists in GitLab, you're specifying which source IP addresses are permitted to interact with your repositories and APIs. This affects both gitStream and your CI/CD runners.
There are two primary cases where this matters for gitStream:
- Webhook Event Handling by gitStream When GitLab triggers a webhook event (e.g., a merge request opened), gitStream may need to make follow-up API calls to GitLab. This can include fetching additional metadata, posting comments to the MR, or performing other actions. These calls are made from the LinearB/gitStream service, which uses a fixed set of IP addresses. These IPs must be added to your GitLab allowlist to ensure proper operation.
- Outbound Requests from Your CI Runner When your pipeline runs gitStream, that runner might also make outbound calls to GitLab—for example, to clone a repository or retrieve commit history. These requests will originate from the runner's IP address.
If you encounter errors due to blocked IPs during your CI runs, it's likely that the runner is using an IP that is not part of the configured allowlist.
Recommended Solution To ensure reliability:
- Add LinearB/gitStream service IPs to your GitLab allowlist (listed above).
- Use self-hosted runners or runners with static IPs so you can manage and allowlist their addresses explicitly.
This combination ensures that both gitStream's internal operations and your CI runners' interactions with GitLab function without network restrictions.
GitLab Installation Overview
- Designate a gitStream user account.
- Create a
cm
repo and.cm
configuration file. - Create a GitLab pipeline.
- 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:
# Use LinearB's AI service to review the changes
linearb_ai_review:
if:
- {{ not pr.draft }}
- {{ not is.bot }}
run:
- action: code-review@v1
args:
approve_on_LGTM: {{ calc.safe_changes }}
# Use LinearB's AI service to add a description to the PR
linearb_ai_description:
if:
- {{ not pr.draft }}
- {{ not is.bot }}
run:
- action: describe-changes@v1
args:
concat_mode: append
# Add a label indicating how long 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 }}
safe_changes: {{ is.formatting or is.docs or is.tests or is.image }}
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'
is:
formatting: {{ source.diff.files | isFormattingChange }}
docs: {{ files | allDocs }}
tests: {{ files | allTests }}
image: {{ files | allImages }}
bot: {{ pr.author | match(list=['github-actions', '_bot_', '[bot]', 'dependabot']) | some }}
Explicit triggers are not supported
The triggers
and on
functionality are not currently supported in GitLab. If you include them in your CM automation files, gitStream will skip the automations entirely.
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
variables:
DOCKER_DRIVER: overlay2
DOCKER_HOST: tcp://docker:2375
DOCKER_TLS_CERTDIR: ""
stages:
- gitstream-main
image: docker:latest
services:
- name: 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
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
- Ensure your runner configuration (
config.toml
for example) has the followig: - Use the tag created above in the workflow file
cm/.gitlab-ci.yml
insteadREGISTERED-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:
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 |