BitBucket Installation – LinearB Support

Use this guide to set up gitStream with Bitbucket Cloud, create a central cm repository, add a Bitbucket Pipeline, and (optionally) configure self-hosted runners.

Important: gitStream for Bitbucket Cloud is currently in beta. If you don’t see the option in your LinearB app, contact the LinearB product team to request access and receive setup instructions.

Time Required: ~10–15 minutes
Difficulty: Easy

Overview

With Bitbucket Cloud, gitStream runs via Bitbucket Pipelines and evaluates rules defined in Continuous Merge (.cm) configuration files.

At a high level, you will:

Designate a dedicated gitStream user account.
Create a cm repository and add a .cm rules file.
Create a bitbucket-pipelines.yml file in the cm repo.
(Optional) Configure self-hosted runners for gitStream.
Install the gitStream service in your Bitbucket workspace and connect it through LinearB.

Before you begin

Prerequisites

Bitbucket Cloud account and workspace.
Bitbucket Pipelines enabled.
Login or create a free account in the LinearB app and follow the Bitbucket integration flow.
A dedicated user for gitStream whose name includes the term gitstream.
Allowed network connection between runners and the following IPs:
- 13.56.203.235
- 54.151.81.98

Required Bitbucket Permissions

Scope	Description
`account: email, read`	Access user account information and email.
`repositories: read, write, admin`	Read, write, and administer repositories.
`pullrequest: read, write`	Read and modify pull requests.
`webhook: read, write`	Read and manage webhooks.
`pipeline: read, write`	Read and write pipelines.
`runner: read, write`	Read and manage runners.

Advanced: network & IP allowlisting

When setting up IP allowlists in Bitbucket, you’re specifying which source IP addresses are permitted to interact with your repositories and APIs. This affects both gitStream and your CI runners.

There are two primary cases where this matters for gitStream:

Webhook event handling by gitStream: When Bitbucket triggers a webhook event (for example, a PR opened), gitStream may need to make follow-up API calls to Bitbucket. These calls are made from the LinearB/gitStream service and use a fixed set of IP addresses.
Outbound requests from your CI runner: When your pipeline runs gitStream, the runner may also make outbound calls to Bitbucket (for example, cloning repos). These requests 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:

Add the LinearB/gitStream service IPs above to your Bitbucket allowlist.
Use self-hosted runners or runners with static IPs so you can manage and allowlist their addresses explicitly.
If you must use Atlassian IP ranges for cloud runners, add the following in your pipeline step runtime block:
```
runtime:
  cloud:
    atlassian-ip-ranges: true
```

Step 1. Designate a gitStream user account

Choose the account that will execute automations

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.

Step 2. Create a `cm` repo & `.cm` configuration file

2.1 – Create the `cm` repository

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

2.2 – Add a `gitstream.cm` configuration file

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

Create a file in the root of the repo, such as gitstream.cm (any name is fine as long as it ends in .cm).
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.

Step 3. Create a Bitbucket Pipeline for gitStream

Add bitbucket-pipelines.yml to the cm repo

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

In the cm repo’s default branch, create bitbucket-pipelines.yml in the root.
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
        
          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.

Step 4. Configure self-hosted runners (optional)

Use self-hosted runners for gitStream

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

Ensure the runner is registered for the cm repository.
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.

Step 5. Install the gitStream service

Enable gitStream for your Bitbucket workspace

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

In the LinearB app, follow the prompts to connect your Bitbucket account and repositories to gitStream.
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.

Verify

Checklist to confirm gitStream is working

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.

Troubleshooting

Problem	Possible cause	How to fix
No gitStream pipeline runs when PRs change	The `gitstream` custom pipeline isn’t configured correctly or gitStream isn’t enabled for the repo	Confirm `bitbucket-pipelines.yml` is in the cm repo root, the `gitstream` custom pipeline exists, and gitStream is enabled for the affected repository in LinearB.
Pipeline runs but no automations fire	No matching rules or invalid syntax in the `.cm` file	Test with a simple “always true” automation (for example, add a comment on every PR). Once that works, reintroduce your conditions.
Errors related to IP allowlists or connectivity	gitStream service IPs or runner IPs are not allowlisted	Allow `13.56.203.235` and `54.151.81.98` in Bitbucket and ensure your runners use allowed/static IPs. If using cloud runners with allowlists, enable `runtime.cloud.atlassian-ip-ranges: true` and the required step size.
Automations silently skipped	Using `triggers` / `on` blocks in CM files	Remove explicit trigger sections from Bitbucket CM files.

FAQs

Do I need a dedicated cm repository?
Yes. The recommended pattern for Bitbucket is to use a cm repository for workspace-level rules and the gitStream pipeline.

Can I define rules per repo as well?
Yes. Workspace-level rules live in the cm repo root. Repo-level rules can be added under a .cm folder inside specific repositories.

Does gitStream change my code?
No. gitStream reads code and metadata and then updates PR metadata (for example, comments or approvals) according to your automations. It does not modify source files.

Can I use label-based automations?
Not on Bitbucket Cloud. Since Bitbucket doesn’t support native PR labels, actions like add-label are not supported.

For further assistance, please contact support.

Next steps