gitStream - GitLab Installation (cloud & self-managed)

gitStream automation rules are executed on behalf of the user account configured when you connect gitStream to your GitLab instance. This account must have the appropriate permissions to the relevant repositories. [oai_citation:7‡gitStream Documentation](https://docs.gitstream.cm/gitlab-installation/)

Requirements:

• The account must have the Maintainer or Owner role for the relevant repos. [oai_citation:8‡gitStream Documentation](https://docs.gitstream.cm/gitlab-installation/)

Recommendations:

• Use a dedicated service account with a meaningful identifier that includes gitstream (case-insensitive), such as gitStream-cm. [oai_citation:9‡gitStream Documentation](https://docs.gitstream.cm/gitlab-installation/)
• You can use a personal account, but all automations will then be executed under that user and may affect LinearB metrics attribution. [oai_citation:10‡gitStream Documentation](https://docs.gitstream.cm/gitlab-installation/)

Make sure to use this account when authorizing GitLab in LinearB. [oai_citation:11‡gitStream Documentation](https://docs.gitstream.cm/gitlab-installation/)

1. In GitLab, create a new project named cm in the same group or a parent group of the target repositories. [oai_citation:12‡gitStream Documentation](https://docs.gitstream.cm/gitlab-installation/)
2. This project is the central place for group-level gitStream rules and the gitStream pipeline.

In the cm project’s default branch (usually main or master):

1. Create a file in the root of the repo named gitstream.cm (the name can vary but must end with .cm). [oai_citation:13‡gitStream Documentation](https://docs.gitstream.cm/gitlab-installation/)
2. Define your automations in that file using YAML + gitStream syntax.

Configuration file locations

• Group-level rules: place .cm files in the root of the cm repository. [oai_citation:14‡gitStream Documentation](https://docs.gitstream.cm/gitlab-installation/)
• Repo-level rules: place .cm files under a .cm directory within individual repositories. [oai_citation:15‡gitStream Documentation](https://docs.gitstream.cm/gitlab-installation/)

Example configuration (aligned with the official GitLab installation page)

# -*- mode: yaml -*-

          # This example configuration provides basic automations to get started with gitStream.

          # View the gitStream quickstart for more 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_author or is.bot_branch) }}

              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

          

          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_author: {{ pr.author | match(list=['github-actions', '_bot_', '[bot]', 'dependabot']) | some }}

            bot_branch: {{ branch.name | match(list=['renovate/']) | some }}

          

Important: 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. [oai_citation:16‡gitStream Documentation](https://docs.gitstream.cm/gitlab-installation/)

In your cm project only, ensure the CI/CD Variables setting “Minimum role to use pipeline variables” is configured to any value other than “No one allowed”. This allows the pipeline in the CM repository to access the necessary variables for gitStream to function properly. [oai_citation:17‡gitStream Documentation](https://docs.gitstream.cm/gitlab-installation/)

You can find this setting under Settings → CI/CD → Variables in the cm project. [oai_citation:18‡gitStream Documentation](https://docs.gitstream.cm/gitlab-installation/)

Create .gitlab-ci.yml in the root of the cm project’s default branch and use the following configuration. [oai_citation:19‡gitStream Documentation](https://docs.gitstream.cm/gitlab-installation/)

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

              - git clone --shallow-since="6 months ago" --no-tags https://gitlab-ci-token:${CI_JOB_TOKEN}${repoUrl} gitstream/repo

              - git clone --depth=1 --no-tags https://gitlab-ci-token:${CI_JOB_TOKEN}${cmUrl} gitstream/cm

              - cd gitstream/repo && git fetch origin $head_ref:$head_ref && git checkout $head_ref

              - 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

          

First, register the runner with a tag, then use that tag in the cm/.gitlab-ci.yml file. [oai_citation:20‡gitStream Documentation](https://docs.gitstream.cm/gitlab-installation/)

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

              - git clone --shallow-since="6 months ago" --no-tags https://gitlab-ci-token:${CI_JOB_TOKEN}${repoUrl} gitstream/repo

              - git clone --depth=1 --no-tags https://gitlab-ci-token:${CI_JOB_TOKEN}${cmUrl} gitstream/cm

              - cd gitstream/repo && git fetch origin $head_ref:$head_ref && git checkout $head_ref

              - 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

          

Ensure your runner configuration (for example config.toml) includes privileged mode. [oai_citation:21‡gitStream Documentation](https://docs.gitstream.cm/gitlab-installation/)

[runners.kubernetes]

          privileged = true

          

Then use the Kubernetes CI template below with your runner tag. [oai_citation:22‡gitStream Documentation](https://docs.gitstream.cm/gitlab-installation/)

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

              - git clone --shallow-since="6 months ago" --no-tags https://gitlab-ci-token:${CI_JOB_TOKEN}${repoUrl} gitstream/repo

              - git clone --depth=1 --no-tags https://gitlab-ci-token:${CI_JOB_TOKEN}${cmUrl} gitstream/cm

              - cd gitstream/repo && git fetch origin $head_ref:$head_ref && git checkout $head_ref

              - 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

          

By default, gitStream pulls the rules engine image from DockerHub each time it is invoked. You can mirror the image to your own registry and update the docker pull line in cm/.gitlab-ci.yml for faster build times and reduced bandwidth usage. [oai_citation:23‡gitStream Documentation](https://docs.gitstream.cm/gitlab-installation/)

script:

          - ...

          - docker pull YOUR-REGISTRY-URL/gitstream/rules-engine:latest

          

1. Log in to LinearB as your designated gitStream user (Step 1). [oai_citation:24‡LinearB HelpDocs](https://linearb.helpdocs.io/article/0xxpvue4s9-connect-git-stream-using-a-git-lab-integration)
2. Navigate to Settings → Git.
3. Locate your GitLab integration.
4. Click Connect gitStream.
5. Follow the prompts to authorize GitLab and confirm the connection. [oai_citation:25‡LinearB HelpDocs](https://linearb.helpdocs.io/article/0xxpvue4s9-connect-git-stream-using-a-git-lab-integration)

• In LinearB:
  • GitLab shows as connected.
  • gitStream is connected to the GitLab integration.
• In GitLab:
  • The cm project exists with:
    • A gitstream.cm file in the root.
    • A .gitlab-ci.yml file in the root.
  • Your runners are online and available.
• Open or update a Merge Request in a target repo and confirm:
  • The gitStream job runs in the cm project.
  • Labels, comments, or approvals appear according to your .cm rules.