---

name: snowsand-bitbucket version: 1.0.1 description: Interact with Bitbucket Cloud via REST API. Use for repository management, pull request operations (list, view, create, comment, approve, merge), branch management, commit history, pipeline status, and workspace/team queries. Triggers on Bitbucket operations, PR reviews, branch management, pipeline checks, or any Atlassian Bitbucket Cloud task.

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:

Credential type	BITBUCKET_USERNAME	BITBUCKET_APP_PASSWORD
Atlassian API token (recommended)	your Atlassian account email	the API token
App Password (legacy)	your Bitbucket username (not email)	the app password

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:

Operation	Command
Repositories
List repos	{baseDir}/scripts/bitbucket.py repos
View repo	{baseDir}/scripts/bitbucket.py repo my-repo
Create repo	{baseDir}/scripts/bitbucket.py create-repo my-new-repo --private
Pull Requests
List PRs	{baseDir}/scripts/bitbucket.py prs my-repo
View PR	{baseDir}/scripts/bitbucket.py pr my-repo 42
Create PR	{baseDir}/scripts/bitbucket.py create-pr my-repo --title "Feature" --source feature-branch
Comment on PR	{baseDir}/scripts/bitbucket.py pr-comment my-repo 42 "LGTM!"
Approve PR	{baseDir}/scripts/bitbucket.py approve my-repo 42
Merge PR	{baseDir}/scripts/bitbucket.py merge my-repo 42
Decline PR	{baseDir}/scripts/bitbucket.py decline my-repo 42
Branches
List branches	{baseDir}/scripts/bitbucket.py branches my-repo
View branch	{baseDir}/scripts/bitbucket.py branch my-repo main
Create branch	{baseDir}/scripts/bitbucket.py create-branch my-repo feature-x --from main
Delete branch	{baseDir}/scripts/bitbucket.py delete-branch my-repo old-feature
Commits
List commits	{baseDir}/scripts/bitbucket.py commits my-repo
View commit	{baseDir}/scripts/bitbucket.py commit my-repo abc123
Pipelines
List pipelines	{baseDir}/scripts/bitbucket.py pipelines my-repo
View pipeline	{baseDir}/scripts/bitbucket.py pipeline my-repo {uuid}
Pipeline steps	{baseDir}/scripts/bitbucket.py pipeline-steps my-repo {uuid}
Workspace
List workspaces	{baseDir}/scripts/bitbucket.py workspaces
Workspace members	{baseDir}/scripts/bitbucket.py members
Current user	{baseDir}/scripts/bitbucket.py me

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:

Strategy	Description
merge_commit	Create a merge commit (default)
squash	Squash all commits into one
fast_forward	Fast-forward if possible

Pipeline States

State	Description
PENDING	Waiting to start
IN_PROGRESS	Currently running
SUCCESSFUL	Completed successfully
FAILED	Completed with failures
STOPPED	Manually stopped

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/