CI/CD Integration - GitHub Actions, GitLab, Jenkins, CircleCI

The Bitbucket CLI can automate pull request workflows, add comments, and manage repositories in your CI/CD pipelines.

Quick Setup

Store credentials as secrets in your CI/CD platform
- BB_USERNAME - Your Bitbucket username
- BB_API_TOKEN - Your Bitbucket API token

Install Bun and the CLI in your pipeline

# Install Bun (required runtime)
curl -fsSL https://bun.sh/install | bash
# Install the CLI (can use npm/pnpm/bun)
npm install -g @pilatos/bitbucket-cli

Authenticate using environment variables
Terminal window
```
bb auth login
```
Run commands with explicit workspace/repo flags
Terminal window
```
bb pr list -w myworkspace -r myrepo --json
```
If your pipeline needs more than the default page size, include --limit <number> on list commands.

Platform Examples

GitHub Actions

name: Bitbucket PR Check

on:
  push:
    branches: [main]
  pull_request:

jobs:
  check-bitbucket-prs:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup Bun
        uses: oven-sh/setup-bun@v1
        with:
          bun-version: latest

      - name: Install Bitbucket CLI
        run: npm install -g @pilatos/bitbucket-cli

      - name: Authenticate
        env:
          BB_USERNAME: ${{ secrets.BB_USERNAME }}
          BB_API_TOKEN: ${{ secrets.BB_API_TOKEN }}
        run: bb auth login

      - name: List Open PRs
        run: |
          bb pr list -w myworkspace -r myrepo --json > prs.json
          echo "Open PRs: $(jq length prs.json)"

Auto-Create PR on Push

name: Auto-Create PR

on:
  push:
    branches:
      - 'feature/**'
      - 'fix/**'

jobs:
  create-pr:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Bun
        uses: oven-sh/setup-bun@v1
        with:
          bun-version: latest

      - name: Setup
        run: npm install -g @pilatos/bitbucket-cli

      - name: Create PR
        env:
          BB_USERNAME: ${{ secrets.BB_USERNAME }}
          BB_API_TOKEN: ${{ secrets.BB_API_TOKEN }}
        run: |
          bb auth login

          BRANCH=${GITHUB_REF#refs/heads/}
          TITLE="$(echo $BRANCH | sed 's/[-_]/ /g' | sed 's/feature\///; s/fix\//Fix: /')"

          # Check if PR already exists
          EXISTING=$(bb pr list -w workspace -r repo --json | \
            jq --arg branch "$BRANCH" '[.pullRequests[] | select(.source.branch.name == $branch)] | length')

          if [ "$EXISTING" -eq 0 ]; then
            bb pr create -w workspace -r repo \
              -t "$TITLE" \
              -s "$BRANCH" \
              -d main
          fi

GitLab CI

stages:
  - check

variables:
  BB_WORKSPACE: myworkspace
  BB_REPO: myrepo

check-prs:
  stage: check
  image: oven/bun:latest

  before_script:
    - npm install -g @pilatos/bitbucket-cli
    - bb auth login

  script:
    - bb pr list -w $BB_WORKSPACE -r $BB_REPO --json
    - bb repo view -w $BB_WORKSPACE -r $BB_REPO

  variables:
    BB_USERNAME: $BB_USERNAME  # From CI/CD variables
    BB_API_TOKEN: $BB_API_TOKEN

Bitbucket Pipelines

Using the CLI within Bitbucket Pipelines itself:

image: oven/bun:latest

pipelines:
  default:
    - step:
        name: Check PRs
        script:
          - npm install -g @pilatos/bitbucket-cli
          - bb auth login
          # Use built-in variables
          - bb pr list -w $BITBUCKET_WORKSPACE -r $BITBUCKET_REPO_SLUG --json

  pull-requests:
    '**':
      - step:
          name: PR Info
          script:
            - npm install -g @pilatos/bitbucket-cli
            - bb auth login
            - bb pr view $BITBUCKET_PR_ID -w $BITBUCKET_WORKSPACE -r $BITBUCKET_REPO_SLUG

definitions:
  caches:
    bun: ~/.bun

Jenkins

Jenkinsfile:

pipeline {
    agent any

    environment {
        BB_USERNAME = credentials('bitbucket-username')
        BB_API_TOKEN = credentials('bitbucket-token')
    }

    stages {
        stage('Setup') {
            steps {
                // Install Bun first (required runtime)
                sh 'curl -fsSL https://bun.sh/install | bash'
                sh 'export PATH="$HOME/.bun/bin:$PATH" && npm install -g @pilatos/bitbucket-cli'
                sh 'export PATH="$HOME/.bun/bin:$PATH" && bb auth login'
            }
        }

        stage('Check PRs') {
            steps {
                sh '''
                    export PATH="$HOME/.bun/bin:$PATH"
                    bb pr list -w myworkspace -r myrepo --json > prs.json
                    PR_COUNT=$(jq '.count' prs.json)
                    echo "Found $PR_COUNT open PRs"
                '''
            }
        }

        stage('Merge Ready PRs') {
            when {
                branch 'main'
            }
            steps {
                sh '''
                    export PATH="$HOME/.bun/bin:$PATH"
                    APPROVED_PRS=$(bb pr list -w myworkspace -r myrepo --json | \
                        jq -r '.pullRequests[] | select(.participants | any(.approved == true)) | .id')

                    for PR_ID in $APPROVED_PRS; do
                        echo "Merging PR #$PR_ID"
                        bb pr merge $PR_ID -w myworkspace -r myrepo --strategy squash
                    done
                '''
            }
        }
    }
}

Azure DevOps

trigger:
  - main

pool:
  vmImage: 'ubuntu-latest'

variables:
  - group: bitbucket-credentials  # Variable group with BB_USERNAME, BB_API_TOKEN

steps:
  - script: |
      curl -fsSL https://bun.sh/install | bash
      echo "##vso[task.prependpath]$HOME/.bun/bin"
    displayName: 'Install Bun'

  - script: npm install -g @pilatos/bitbucket-cli
    displayName: 'Install Bitbucket CLI'

  - script: bb auth login
    displayName: 'Authenticate'
    env:
      BB_USERNAME: $(BB_USERNAME)
      BB_API_TOKEN: $(BB_API_TOKEN)

  - script: |
      bb pr list -w myworkspace -r myrepo --json
    displayName: 'List PRs'

Common Use Cases

Auto-Create PR for Dependency Updates

# GitHub Actions example
name: Dependency Update PR

on:
  schedule:
    - cron: '0 9 * * 1'  # Weekly on Monday

jobs:
  update-deps:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Bun
        uses: oven-sh/setup-bun@v1
        with:
          bun-version: latest

      - name: Update dependencies
        run: |
          bun update
          git config user.name "Bot"
          git config user.email "bot@example.com"
          git checkout -b deps/weekly-update
          git add package*.json
          git commit -m "chore: weekly dependency update" || exit 0
          git push -u origin deps/weekly-update

      - name: Create Bitbucket PR
        env:
          BB_USERNAME: ${{ secrets.BB_USERNAME }}
          BB_API_TOKEN: ${{ secrets.BB_API_TOKEN }}
        run: |
          npm install -g @pilatos/bitbucket-cli
          bb auth login
          bb pr create -w workspace -r repo \
            -t "chore: Weekly dependency update" \
            -b "Automated dependency updates" \
            -s deps/weekly-update \
            -d main

Merge Approved PRs Automatically

#!/bin/bash
# auto-merge.sh - Run in CI on schedule

set -e

WORKSPACE="myworkspace"
REPO="myrepo"

# Find PRs that are approved and have passing builds
approved_prs=$(bb pr list -w "$WORKSPACE" -r "$REPO" --json | jq -r '
  .pullRequests[] |
  select(.participants | any(.approved == true)) |
  select(.state == "OPEN") |
  .id
')

for pr_id in $approved_prs; do
  echo "Attempting to merge PR #$pr_id..."

  if bb pr merge "$pr_id" -w "$WORKSPACE" -r "$REPO" --strategy squash --close-source-branch; then
    echo "Successfully merged PR #$pr_id"
  else
    echo "Could not merge PR #$pr_id (may have conflicts or failing checks)"
  fi

  sleep 2
done

Generate Changelog from Merged PRs

#!/bin/bash
WORKSPACE="myworkspace"
REPO="myrepo"
SINCE_DATE=$(date -d '7 days ago' +%Y-%m-%d)

echo "# Changelog - Week of $(date +%Y-%m-%d)"
echo ""

bb pr list -w "$WORKSPACE" -r "$REPO" -s MERGED --json | jq -r --arg since "$SINCE_DATE" '
  .pullRequests[] |
  select(.updated_on >= $since) |
  "- \(.title) (#\(.id)) by @\(.author.nickname // .author.display_name // \"unknown\")"
'

Security Considerations

Token Scopes

Create a dedicated CI/CD token with minimal permissions:

Use Case	Required Scopes
Read-only checks	`repository:read`, `pullrequest:read`
Create PRs	+ `pullrequest:write`
Merge PRs	+ `pullrequest:write`
Delete repos	+ `repository:admin`

Secrets Management

Store in Settings > Secrets and variables > Actions

Audit Logging

Track CLI usage in your pipelines:

echo "Running bb at $(date) by ${CI_USER:-unknown}"
bb pr list -w workspace -r repo --json | tee pr-list-$(date +%s).json

Troubleshooting CI/CD

Authentication Fails

Error: Authentication required

Check:

Environment variables are set correctly
Secrets are available to the job
Token hasn’t expired

Debug:

echo "Username set: $([ -n "$BB_USERNAME" ] && echo 'yes' || echo 'no')"
echo "Token set: $([ -n "$BB_API_TOKEN" ] && echo 'yes' || echo 'no')"

Rate Limiting in Loops

Add delays between API calls:

for pr_id in $pr_ids; do
  bb pr view "$pr_id" --json
  sleep 2  # Prevent rate limiting
done

Command Not Found

Ensure Bun and the CLI are installed:

# Install Bun (required runtime)
curl -fsSL https://bun.sh/install | bash
export PATH="$HOME/.bun/bin:$PATH"

# Install CLI
npm install -g @pilatos/bitbucket-cli
bb --version