gitStream - BitBucket Installation

gitStream runs automations on behalf of a specific Bitbucket user — the one you use when connecting gitStream via LinearB. This account must have appropriate permissions to the relevant repositories.

Required:

• A meaningful account identifier whose name contains the string gitstream (case insensitive), such as gitStream-cm.

Recommendation:

• Use a dedicated service account so its actions are easy to identify in PR history and audits.

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

1. In Bitbucket, create a new repository named cm in your workspace.
2. This repository must reside in the same project as your target repositories.
3. Use this repo as the central place for your workspace-level gitStream rules and pipeline configuration.

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

1. Create a file in the root of the repo, such as gitstream.cm (any name is fine as long as it ends in .cm).
2. Define your automations and custom expressions in that file.

Important behavior:

• Ensure all changes to your .cm configuration files are committed to the default branch before proceeding.
• Workspace-level rules must be placed in the cm repository’s root directory.
• You can also define repo-level rules under a .cm folder in each connected repository.

Example configuration

# -*- mode: yaml -*-

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

          manifest:

            version: 1.0

          

          automations:

            # Use LinearB's AI service to review the changes

            linearb_ai_review:

              if:

                - {{ not pr.draft }}

                - {{ not (is.bot_author or is.bot_branch) }}

              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 comment indicating how long it will take to review the PR

            estimated_time_to_review:

              if:

                - true

              run:

                - action: add-comment@v1

                  args:

                    comment: "{{ calc.etr }} min review"

          

            # Request changes when Jira ticket info is missing

            request_missing_jira_info:

              if:

                - {{ not (has.jira_ticket_in_title or has.jira_ticket_in_desc) }}

              run:

                - action: request-changes@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 }}

          

Bitbucket limitations:

• Labels are not supported: Bitbucket does not have a native labeling feature, so add-label is not supported.
• Explicit triggers are not supported: triggers / on blocks are not currently supported. If you include them in CM files, gitStream will skip those automations.

Once your gitStream configuration file is set up, you need a Bitbucket Pipelines configuration file to trigger gitStream automations.

1. In the cm repo’s default branch, create bitbucket-pipelines.yml in the root.
2. Add the following configuration:

# Code generated by gitStream - DO NOT EDIT

          

          image: atlassian/default-image:4

          

          pipelines:

            # Pipelines that can only be triggered manually

            custom:

              gitstream:

                - variables:

                    - name: client_payload

                      description: the client payload

                    - name: head_ref

                      description: the head sha

                    - name: base_ref

                      description: The base sha

                    - name: resolver_url

                      description: the resolver url to pass results to

                    - name: resolver_token

                      description: Optional resolver token for resolver service

                    - name: debug_mode

                      description: Debug mode

                      default: 'true'

                    - name: oauth_token

                      description: token to do operations in bitbucket

                    - name: full_repo

                      description: workspace/repo

                - step:

                    name: /:\ gitstream workflow automation

                    ##### For cloud runners with IP whitelist, uncomment the section below

                    # size: 4x # Required as atlassian-ip-ranges supported only on 4x or more

                    # runtime:

                    #   cloud:

                    #     atlassian-ip-ranges: true

                    ##### End of section

                    #

                    ##### For self-hosted runners, uncomment the section below

                    # runs-on:

                    #   - self.hosted # Required to indicate a self-hosted runner

                    #   - cmgitstreamrunner # Custom label that must be added to your self-hosted runner

                    ##### End of section

                    max-time: 15

                    clone:

                      enabled: false

                    services:

                      - docker

                    script:

                      - git clone --shallow-since="6 months ago" --no-tags https://x-token-auth:$oauth_token@bitbucket.org/$full_repo.git gitstream/repo

                      - git clone --depth=1 --no-tags https://x-token-auth:$oauth_token@bitbucket.org/$BITBUCKET_WORKSPACE/$BITBUCKET_REPO_SLUG.git 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 $BITBUCKET_CLONE_DIR/gitstream:/code \

                        -e HEAD_REF=$head_ref \

                        -e BASE_REF=$base_ref \

                        -e RUN_ID=$BITBUCKET_BUILD_NUMBER \

                        -e CLIENT_PAYLOAD="$client_payload" \

                        -e RULES_RESOLVER_URL=$resolver_url \

                        -e RULES_RESOLVER_TOKEN=$resolver_token \

                        -e DEBUG_MODE=$debug_mode gitstream/rules-engine:latest

          

This pipeline uses Docker to run the gitStream rules engine image and evaluate your .cm configuration.

If you prefer to run gitStream on your own infrastructure, configure Bitbucket self-hosted runners for the cm repository.

1. Ensure the runner is registered for the cm repository.
2. In bitbucket-pipelines.yml, uncomment and use:

runs-on:

            - self.hosted # Required to indicate a self-hosted runner

            - cmgitstreamrunner # Must use custom label for gitStream runner

          

Required runner labels in Bitbucket:

• self.hosted (provided by default)
• linux (provided by default)
• cmgitstreamrunner (custom – required for gitStream)

The cmgitstreamrunner label is required for gitStream to properly identify and use your self-hosted runner.

To complete the setup, install the gitStream service in your Bitbucket workspace.

1. In the LinearB app, follow the prompts to connect your Bitbucket account and repositories to gitStream.
2. Make sure you authorize Bitbucket using the dedicated gitStream user account from Step 1.

Once installed, gitStream can trigger the custom pipeline in your cm repository when PR events occur in connected repositories.

• In LinearB:
  • Bitbucket shows as connected.
  • gitStream is enabled for the Bitbucket integration (if your beta access is active).
• In Bitbucket:
  • The cm repository exists with:
    • A *.cm file in the root (for example, gitstream.cm).
    • A bitbucket-pipelines.yml file in the root.
  • Bitbucket Pipelines are enabled.
  • Runners (cloud or self-hosted) are available.
• Open or update a PR in a connected repository and confirm:
  • The gitstream custom pipeline runs in the cm repository.
  • Comments, approvals, or other PR updates appear according to your .cm rules.