Snowsand Bitbucket

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 - @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/