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