Bitbucket Cloud Integration

Bitbucket Cloud REST API v2 integration for repository management, pull requests, branches, commits, and pipelines.

Authentication

Bitbucket Cloud REST v2 uses HTTP Basic auth. Required environment variables:

• BITBUCKET_WORKSPACE - Default workspace slug (e.g., myteam)
• BITBUCKET_USERNAME - Identity for Basic auth (see pairing below)
• BITBUCKET_APP_PASSWORD - Secret for Basic auth (see pairing below)

Two credential types work. Use the matching username for each:

Note: despite the variable name, BITBUCKET_APP_PASSWORD accepts an Atlassian API token. For SnowSand's Atlassian - <user>@snowsand.com vault items, the bitbucket-token field is an Atlassian API token, so pair it with the account email as the username.

Atlassian API tokens: https://id.atlassian.com/manage-profile/security/api-tokens App Passwords (legacy): https://bitbucket.org/account/settings/app-passwords/

Required scopes/permissions:

• Repositories: Read, Write (for repo operations)
• Pull requests: Read, Write (for PR operations)
• Pipelines: Read (for pipeline status)
• Account: Read (for user info)

Test connection:

curl -s -u "$BITBUCKET_USERNAME:$BITBUCKET_APP_PASSWORD" \
  "https://api.bitbucket.org/2.0/user" | jq .

Cross-workspace listing note: Bitbucket CHANGE-2770 removed the old GET /2.0/workspaces and GET /2.0/user/permissions/workspaces endpoints (they now return HTTP 410). bitbucket.py workspaces uses the supported replacement GET /2.0/user/workspaces. All other commands are workspace-scoped and unaffected.

Quick Reference

All operations use the {baseDir}/scripts/bitbucket.py script:

Common Workflows

Repository Management

# List all repositories in workspace
{baseDir}/scripts/bitbucket.py repos

# List with pagination
{baseDir}/scripts/bitbucket.py repos --page 2 --pagelen 25

# View specific repository details
{baseDir}/scripts/bitbucket.py repo my-repo

# Create a new private repository
{baseDir}/scripts/bitbucket.py create-repo my-new-repo --private --description "Project description"

# Create public repository with specific project
{baseDir}/scripts/bitbucket.py create-repo my-public-repo --project PROJ

Pull Request Workflow

# List open pull requests
{baseDir}/scripts/bitbucket.py prs my-repo

# List all PRs (including merged/declined)
{baseDir}/scripts/bitbucket.py prs my-repo --state all

# View PR details
{baseDir}/scripts/bitbucket.py pr my-repo 42

# Create a pull request
{baseDir}/scripts/bitbucket.py create-pr my-repo \
  --title "Add new feature" \
  --source feature-branch \
  --destination main \
  --description "This PR adds..."

# Add a comment
{baseDir}/scripts/bitbucket.py pr-comment my-repo 42 "Looks good, just one question..."

# Approve the PR
{baseDir}/scripts/bitbucket.py approve my-repo 42

# Unapprove (remove approval)
{baseDir}/scripts/bitbucket.py unapprove my-repo 42

# Request changes
{baseDir}/scripts/bitbucket.py request-changes my-repo 42

# Merge with default strategy
{baseDir}/scripts/bitbucket.py merge my-repo 42

# Merge with specific strategy
{baseDir}/scripts/bitbucket.py merge my-repo 42 --strategy squash

# Decline a PR
{baseDir}/scripts/bitbucket.py decline my-repo 42

Branch Operations

# List all branches
{baseDir}/scripts/bitbucket.py branches my-repo

# View branch details
{baseDir}/scripts/bitbucket.py branch my-repo feature-x

# Create branch from main
{baseDir}/scripts/bitbucket.py create-branch my-repo feature-y --from main

# Create branch from specific commit
{baseDir}/scripts/bitbucket.py create-branch my-repo hotfix-1 --from abc123def

# Delete a branch (cannot delete main branch)
{baseDir}/scripts/bitbucket.py delete-branch my-repo old-feature

Commit History

# List recent commits (default branch)
{baseDir}/scripts/bitbucket.py commits my-repo

# Commits on specific branch
{baseDir}/scripts/bitbucket.py commits my-repo --branch feature-x

# Limit results
{baseDir}/scripts/bitbucket.py commits my-repo --pagelen 10

# View specific commit
{baseDir}/scripts/bitbucket.py commit my-repo abc123def456

Pipeline Status

# List recent pipelines
{baseDir}/scripts/bitbucket.py pipelines my-repo

# Filter by status
{baseDir}/scripts/bitbucket.py pipelines my-repo --status SUCCESSFUL
{baseDir}/scripts/bitbucket.py pipelines my-repo --status FAILED

# View pipeline details
{baseDir}/scripts/bitbucket.py pipeline my-repo '{pipeline-uuid}'

# View pipeline steps
{baseDir}/scripts/bitbucket.py pipeline-steps my-repo '{pipeline-uuid}'

# Trigger a pipeline
{baseDir}/scripts/bitbucket.py run-pipeline my-repo --branch main

Workspace and User Info

# List accessible workspaces
{baseDir}/scripts/bitbucket.py workspaces

# List workspace members
{baseDir}/scripts/bitbucket.py members

# Get current user info
{baseDir}/scripts/bitbucket.py me

Merge Strategies

When merging PRs, available strategies are:

Pipeline States

Error Handling

Common errors:

• 401 Unauthorized: Check BITBUCKET_USERNAME and BITBUCKET_APP_PASSWORD
• 403 Forbidden: App password lacks required permissions
• 404 Not Found: Repository, PR, or branch doesn't exist
• 400 Bad Request: Invalid parameters or branch name

Raw API Access

For operations not covered by the script:

# GET request
curl -s -u "$BITBUCKET_USERNAME:$BITBUCKET_APP_PASSWORD" \
  "https://api.bitbucket.org/2.0/repositories/$BITBUCKET_WORKSPACE/my-repo" | jq .

# POST request
curl -s -X POST -u "$BITBUCKET_USERNAME:$BITBUCKET_APP_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"content": {"raw": "Comment text"}}' \
  "https://api.bitbucket.org/2.0/repositories/$BITBUCKET_WORKSPACE/my-repo/pullrequests/42/comments" | jq .

API docs: https://developer.atlassian.com/cloud/bitbucket/rest/