pi-bitbucket

Bitbucket Cloud integration for Pi. Manage repositories, pull requests, branches, pipelines, and issues — all from within your coding agent.

Install

pi install npm:pi-bitbucket

Or try it without installing:

pi -e npm:pi-bitbucket

Setup

1. Create a Bitbucket API Token

Go to Bitbucket API Tokens and create a token with these permissions:

• Repositories: Read, Write
• Pull Requests: Read, Write
• Pipelines: Read, Write
• Issues: Read, Write

2. Configure

On first run, pi-bitbucket scaffolds a config file at .pi/bitbucket.json. Fill in your credentials:

{
  "workspace": "my-workspace",
  "username": "my-username",
  "apiToken": "ATBBxxxxxxxxxxxx",
  "defaultRepo": "my-repo",
  "readOnly": false
}

Upgrading from v1.0? The appPassword field still works but is deprecated. Rename it to apiToken when convenient.

Config is loaded from (first match wins):

Location	Scope
.pi/bitbucket.json	Project
~/.pi/agent/bitbucket.json	Global
Environment variables	Global

Environment Variables

Instead of a JSON file, set:

export BITBUCKET_WORKSPACE=my-workspace
export BITBUCKET_USERNAME=my-username
export BITBUCKET_API_TOKEN=ATBBxxxxxxxxxxxx
export BITBUCKET_DEFAULT_REPO=my-repo      # optional
export BITBUCKET_READ_ONLY=true            # optional

ENV References

Config values can reference environment variables with the ENV: prefix:

{
  "workspace": "my-workspace",
  "username": "ENV:BB_USER",
  "apiToken": "ENV:BB_API_TOKEN"
}

Read-Only Mode

Set "readOnly": true to block write operations (create PR, merge, approve, comment, trigger pipeline, create issue). Useful for shared environments or CI.

Actions

All 16 actions are available via the bitbucket tool. If repo is omitted, defaultRepo from config is used.

Repositories

Action	Parameters	Description
list_repos	page?	List all repositories in the workspace
get_repo	repo?	Get detailed repository info

Pull Requests

Action	Parameters	Description
list_prs	repo?, state?, page?	List pull requests. State: OPEN, MERGED, DECLINED, SUPERSEDED
get_pr	repo?, pr_id	Get PR details including diff stats, reviewers, approvals
create_pr	repo?, title, source_branch, destination_branch?, description?, close_source?	Create a pull request
merge_pr	repo?, pr_id, merge_strategy?, close_source?	Merge a PR. Strategy: merge_commit, squash, fast_forward
decline_pr	repo?, pr_id	Decline a pull request
approve_pr	repo?, pr_id	Approve a pull request
comment_pr	repo?, pr_id, comment	Add a comment to a pull request

Branches

Action	Parameters	Description
list_branches	repo?, page?	List branches sorted by most recent commit

Pipelines

Action	Parameters	Description
list_pipelines	repo?, page?	List recent pipelines
get_pipeline	repo?, pipeline_uuid	Get pipeline details and status
trigger_pipeline	repo?, target_branch	Trigger a pipeline on a branch

Issues

Action	Parameters	Description
list_issues	repo?, state?, page?	List issues. State: new, open, resolved, on hold, invalid, duplicate, wontfix, closed
get_issue	repo?, issue_id	Get issue details
create_issue	repo?, title, description?, kind?, priority?	Create an issue. Kind: bug, enhancement, proposal, task. Priority: trivial, minor, major, critical, blocker

Prompt Templates

Use these built-in prompt templates in Pi:

• /pr-review <pr_id> — Review a pull request for bugs, security issues, and code quality
• /repo-overview — Get a comprehensive overview of the repository

Skills

The bitbucket skill teaches the agent how to use the Bitbucket tool effectively. It's loaded automatically when Pi detects a Bitbucket-related task.

Package Contents

pi-bitbucket/
├── extensions/
│   └── bitbucket.ts       # Extension: tool, config, API client, TUI rendering
├── skills/
│   └── bitbucket/
│       └── SKILL.md        # Agent skill for Bitbucket workflows
├── prompts/
│   ├── pr-review.md        # PR review prompt template
│   └── repo-overview.md    # Repository overview prompt template
├── package.json
├── LICENSE
└── README.md

License

MIT