snowsand-bitbucket（雪沙钻头桶）

Bitbucket Cloud Integration

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

Authentication

Bitbucket Cloud uses App Password authentication. Required environment variables:

• BITBUCKET_WORKSPACE - Default workspace slug (e.g., myteam)
• BITBUCKET_USERNAME - Bitbucket username (not email)
• BITBUCKET_APP_PASSWORD - App password from https://bitbucket.org/account/settings/app-passwords/

Create an App Password with required 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 .

Quick Reference

All operations use the scripts/bitbucket.py script:

Common Workflows

Repository Management

# List all repositories in workspace
bitbucket.py repos

# List with pagination
bitbucket.py repos --page 2 --pagelen 25

# View specific repository details
bitbucket.py repo my-repo

# Create a new private repository
bitbucket.py create-repo my-new-repo --private --description "Project description"

# Create public repository with specific project
bitbucket.py create-repo my-public-repo --project PROJ

Pull Request Workflow

# List open pull requests
bitbucket.py prs my-repo

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

# View PR details
bitbucket.py pr my-repo 42

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

# Add a comment
bitbucket.py pr-comment my-repo 42 "Looks good, just one question..."

# Approve the PR
bitbucket.py approve my-repo 42

# Unapprove (remove approval)
bitbucket.py unapprove my-repo 42

# Request changes
bitbucket.py request-changes my-repo 42

# Merge with default strategy
bitbucket.py merge my-repo 42

# Merge with specific strategy
bitbucket.py merge my-repo 42 --strategy squash

# Decline a PR
bitbucket.py decline my-repo 42

Branch Operations

# List all branches
bitbucket.py branches my-repo

# View branch details
bitbucket.py branch my-repo feature-x

# Create branch from main
bitbucket.py create-branch my-repo feature-y --from main

# Create branch from specific commit
bitbucket.py create-branch my-repo hotfix-1 --from abc123def

# Delete a branch (cannot delete main branch)
bitbucket.py delete-branch my-repo old-feature

Commit History

# List recent commits (default branch)
bitbucket.py commits my-repo

# Commits on specific branch
bitbucket.py commits my-repo --branch feature-x

# Limit results
bitbucket.py commits my-repo --pagelen 10

# View specific commit
bitbucket.py commit my-repo abc123def456

Pipeline Status

# List recent pipelines
bitbucket.py pipelines my-repo

# Filter by status
bitbucket.py pipelines my-repo --status SUCCESSFUL
bitbucket.py pipelines my-repo --status FAILED

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

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

# Trigger a pipeline
bitbucket.py run-pipeline my-repo --branch main

Workspace and User Info

# List accessible workspaces
bitbucket.py workspaces

# List workspace members
bitbucket.py members

# Get current user info
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/