# pi-bitbucket

Bitbucket Cloud integration for [Pi](https://github.com/badlogic/pi). Manage repositories, pull requests, branches, pipelines, and issues — all from within your coding agent.

## Install

```bash
pi install npm:pi-bitbucket
```

Or try it without installing:

```bash
pi -e npm:pi-bitbucket
```

## Setup

### 1. Create a Bitbucket API Token

Go to [Bitbucket API Tokens](https://bitbucket.org/account/settings/app-passwords/) 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:

```json
{
  "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:

```bash
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:

```json
{
  "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