Skip to content

How to Setup gitStream with Bitbucket Cloud

gitStream for Bitbucket Cloud is currently in beta

To start automating your Bitbucket pull requests and enhancing your development workflow, please contact our product team to request access and receive setup instructions. We’d love to hear your feedback and collaborate to improve this integration during the beta phase. Thank you for your interest!

Prerequisites

  1. Bitbucket Cloud account
  2. Bitbucket Pipelines enabled
  3. Login, or create a free account on the LinearB app, and follow the steps to connect gitStream using a Bitbucket integration.
  4. A dedicated user for gitStream, whose name includes the term "gitstream".
  5. Allowed network connection between the runners and the following IPs:
    • 13.56.203.235
    • 54.151.81.98
Understanding IP Allowlisting for gitStream

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/CD runners.

There are two primary cases where this matters for gitStream:

  1. Webhook Event Handling by gitStream When Bitbucket triggers a webhook event (e.g., a pull request opened), gitStream may need to make follow-up API calls to Bitbucket. This can include fetching additional metadata, posting comments to the PR, 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 Bitbucket allowlist to ensure proper operation.
  2. Outbound Requests from Your CI Runner When your pipeline runs gitStream, that runner might also make outbound calls to Bitbucket—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 Bitbucket 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 Bitbucket function without network restrictions.

Bitbucket Installation Overview

  1. Designate a gitStream user account.
  2. Create a cm repo and .cm configuration file.
  3. Create a Bitbucket pipeline.
  4. Install the gitStream service.

Designate a gitStream User Account

gitStream automation rules are executed by the user account configured when you authorize LinearB. A meaningful account identifier whose name contains the string gitstream (case insensitive), such as gitStream-cm, is required to ensure clarity and proper identification of the automated actions. This account must have the necessary permissions to the relevant repositories.

Use this account when you integrate gitStream

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

Create a cm repo and .cm configuration file.

Create a cm repository in your Bitbucket workspace. This repository must reside in the same project as your 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 can have any name but must end with the .cm extension.

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 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 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-comment@v1
        args:
          comment: "{{ calc.etr }} min review"

  # Request changes by PR authors when they fail to reference Jira tickets in the PR title or description.
  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


# +----------------------------------------------------------------------------+
# | 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 }}

Create a Bitbucket Pipeline

Once your gitStream configuration file is set up, you need a Bitbucket Pipelines configuration file to trigger gitStream automations. Create a bitbucket-pipelines.yml file in your cm repository's default branch and 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
          max-time: 15
          clone:
            enabled: false
          services:
            - docker
          script:
            - git clone https://x-token-auth:$oauth_token@bitbucket.org/$full_repo.git gitstream/repo
            - git clone https://x-token-auth:$oauth_token@bitbucket.org/$BITBUCKET_WORKSPACE/$BITBUCKET_REPO_SLUG.git gitstream/cm
            - cd gitstream/repo
            - git fetch --all
            - git checkout $base_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

Labels are not supported

The add-label action is not supported in Bitbucket as Bitbucket does not have a native labeling feature.

Explicit triggers are not supported

The triggers and on functionality are not currently supported in Bitbucket. If you include them in your CM automation files, gitStream will skip the automations entirely.

Install the gitStream Service

To complete the setup, install the gitStream service in your Bitbucket workspace. Follow the instructions provided in the LinearB app to connect your Bitbucket account and repositories to gitStream.

Next Step

If you successfully complete these instructions, gitStream will now automate your code review workflows in Bitbucket.

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 Bitbucket Permissions

The required permissions are:

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.