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

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

Bitbucket Installation Overview

Designate a gitStream user account.
Create a cm repo and .cm configuration file.
Create a Bitbucket pipeline.
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:
  # Add a comment that indicates how many minutes 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 }}

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}/) }}

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

Note

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

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.