BitBucket Server

This skill provides tools for interacting with BitBucket Server's REST API, focusing on Pull Request management workflows.

Prerequisites

The following environment variables must be set:

• BITBUCKET_URL - Base URL of the BitBucket Server instance (e.g., https://bitbucket.example.com)
• BITBUCKET_USER - Username for authentication
• BITBUCKET_TOKEN - Personal access token for authentication

Available Commands

The scripts/bitbucket_api.py script provides a CLI for BitBucket Server operations. Execute it with Python 3:

python3 scripts/bitbucket_api.py <command> [options]

Pull Request Commands

Comment Commands

Task Commands

Command Usage Examples

List Pull Requests

# List all open PRs in a repository
python3 scripts/bitbucket_api.py list-prs --project MYPROJ --repo my-repo

# List PRs with specific state
python3 scripts/bitbucket_api.py list-prs --project MYPROJ --repo my-repo --state MERGED

Get Pull Request Details

python3 scripts/bitbucket_api.py get-pr --project MYPROJ --repo my-repo --pr-id 42

Create a Pull Request

python3 scripts/bitbucket_api.py create-pr \
  --project MYPROJ \
  --repo my-repo \
  --title "Add new feature" \
  --from-branch feature/my-feature \
  --to-branch main \
  --description "Description of changes"

Get Diff

python3 scripts/bitbucket_api.py get-diff --project MYPROJ --repo my-repo --pr-id 42

Work with Comments

# Get all comments
python3 scripts/bitbucket_api.py get-comments --project MYPROJ --repo my-repo --pr-id 42

# Add a general comment
python3 scripts/bitbucket_api.py add-comment \
  --project MYPROJ --repo my-repo --pr-id 42 \
  --text "This looks good!"

# Add an inline comment on a specific file and line
python3 scripts/bitbucket_api.py add-comment \
  --project MYPROJ --repo my-repo --pr-id 42 \
  --text "Consider renaming this variable" \
  --file-path src/main.py --line 42 --line-type ADDED

# Reply to a comment
python3 scripts/bitbucket_api.py reply-comment \
  --project MYPROJ --repo my-repo --pr-id 42 \
  --comment-id 123 --text "Fixed!"

Work with Tasks

Tasks in BitBucket Server are comments with BLOCKER severity. They are managed via the Comments API.

# List all tasks (BLOCKER comments)
python3 scripts/bitbucket_api.py get-tasks --project MYPROJ --repo my-repo --pr-id 42

# Complete a single task
python3 scripts/bitbucket_api.py complete-task --project MYPROJ --repo my-repo --pr-id 42 --comment-id 456

# Complete multiple tasks at once (comma-separated IDs)
python3 scripts/bitbucket_api.py complete-tasks --project MYPROJ --repo my-repo --pr-id 42 --comment-ids 456,789,123

# Reopen a single task
python3 scripts/bitbucket_api.py reopen-task --project MYPROJ --repo my-repo --pr-id 42 --comment-id 456

# Reopen multiple tasks at once
python3 scripts/bitbucket_api.py reopen-tasks --project MYPROJ --repo my-repo --pr-id 42 --comment-ids 456,789

PR Actions

# Approve a PR
python3 scripts/bitbucket_api.py approve --project MYPROJ --repo my-repo --pr-id 42

# Merge a PR
python3 scripts/bitbucket_api.py merge --project MYPROJ --repo my-repo --pr-id 42

# Decline a PR
python3 scripts/bitbucket_api.py decline --project MYPROJ --repo my-repo --pr-id 42

Workflow Guidelines

Reviewing a Pull Request

1. Get PR details to understand the context
2. Get the diff to review code changes
3. Get existing comments to see discussion
4. Add comments or inline comments as needed
5. Check and manage tasks if present
6. Approve or request changes

Creating a Pull Request

1. Ensure the source branch exists and has commits
2. Create the PR with a descriptive title and description
3. The script returns the PR ID and URL on success

Managing Tasks

Tasks in BitBucket Server are comments with BLOCKER severity. Use get-tasks to list all tasks and their status (returns comment IDs), then complete-task or reopen-task to change their state. The comment ID from get-tasks output is used as --comment-id for task operations.

Error Handling

The script outputs JSON for successful operations and error messages for failures. Common errors:

• Missing environment variables: Ensure BITBUCKET_URL, BITBUCKET_USER, and BITBUCKET_TOKEN are set
• Authentication failed: Verify credentials and token permissions
• Resource not found: Check project, repository, and PR ID values

Additional Reference

For detailed API endpoint documentation, see references/api_endpoints.md.