Bitbucket server

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 root (e.g., https://bitbucket.example.com or https://bitbucket.example.com/bitbucket). Must not include /projects/..., /rest/..., or /scm/... — the script will hard-fail with a clear error if it detects those suffixes.
• BITBUCKET_USER - Username for authentication
• BITBUCKET_TOKEN - Personal access token for authentication

The script is self-contained via PEP 723 inline script metadata and requires uv. Run it directly — no pip install or venv needed:

scripts/bitbucket_api.py <command> [options]

--project and --repo are optional for all commands: if omitted they are inferred automatically from the origin git remote of the current working directory.

Available Commands

Pull Request Commands

Command	Description
list-prs	List pull requests with optional status filter
get-pr	Get details of a specific pull request
current-pr	Show the open PR for the current git branch
create-pr	Create a new pull request
get-diff	Get the diff of a pull request (unified diff by default)
approve	Approve a pull request
merge	Merge a pull request
decline	Decline a pull request

Comment Commands

Command	Description
get-comments	Get all comments and activities on a pull request
add-comment	Add a general or inline comment to a pull request
reply-comment	Reply to an existing comment

Task Commands

Command	Description
get-tasks	List all tasks on a pull request
complete-task	Mark a single task as completed
complete-tasks	Mark multiple tasks as completed at once
reopen-task	Reopen a single completed task
reopen-tasks	Reopen multiple tasks at once

Command Usage Examples

List Pull Requests

# List open PRs — project/repo inferred from git remote
scripts/bitbucket_api.py list-prs

# Explicit project/repo, specific state
scripts/bitbucket_api.py list-prs --project MYPROJ --repo my-repo --state MERGED

# All PRs regardless of state
scripts/bitbucket_api.py list-prs --state ALL

Get Pull Request Details

# By ID
scripts/bitbucket_api.py get-pr --pr-id 42

# PR for the current branch
scripts/bitbucket_api.py current-pr

Create a Pull Request

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

Get Diff

# Unified diff (default, human/LLM readable)
scripts/bitbucket_api.py get-diff --pr-id 42

# Raw Bitbucket JSON structure
scripts/bitbucket_api.py get-diff --pr-id 42 --format json

Work with Comments

# Get all comments
scripts/bitbucket_api.py get-comments --pr-id 42

# Add a general comment
scripts/bitbucket_api.py add-comment --pr-id 42 --text "This looks good!"

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

# Reply to a comment
scripts/bitbucket_api.py reply-comment --pr-id 42 --comment-id 123 --text "Fixed!"

reply-comment uses the same PR comments collection endpoint as the Bitbucket web UI and sets parent.id in the JSON body.

Work with Tasks

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

# List all tasks (BLOCKER comments)
scripts/bitbucket_api.py get-tasks --pr-id 42

# Complete a single task
scripts/bitbucket_api.py complete-task --pr-id 42 --comment-id 456

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

# Reopen a single task
scripts/bitbucket_api.py reopen-task --pr-id 42 --comment-id 456

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

PR Actions

scripts/bitbucket_api.py approve --pr-id 42
scripts/bitbucket_api.py merge   --pr-id 42
scripts/bitbucket_api.py decline --pr-id 42

Workflow Guidelines

Reviewing a Pull Request

1. Use current-pr (or list-prs) to find the PR ID
2. get-diff to review code changes (unified diff by default)
3. get-comments to see existing discussion
4. add-comment or reply-comment as needed
5. get-tasks / complete-task to manage tasks
6. approve when satisfied

Creating a Pull Request

1. Ensure the source branch exists and has commits
2. create-pr — project/repo inferred from git remote if not specified
3. The script returns the PR ID and URL on success

Managing Tasks

Tasks are BLOCKER-severity comments. Use get-tasks to list them (returns comment IDs), then complete-task or reopen-task to change state.

Error Handling

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

• Missing environment variables: ensure BITBUCKET_URL, BITBUCKET_USER, and BITBUCKET_TOKEN are set
• Bad BITBUCKET_URL: the script hard-fails with a descriptive message if the URL contains API path suffixes
• --project / --repo not resolvable: supply them explicitly or run from inside the git repo
• 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.