# Bitbucket Helper

> Bitbucket PR operations: create, read, update, approve, diff.

- Skill: `darknesskiller/bitbucket-helper` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add darknesskiller/bitbucket-helper`
- Raw SKILL.md: https://api.skillmd.com/api/skills/darknesskiller/bitbucket-helper/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: darknesskiller (https://skillmd.com/u/darknesskiller)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/darknesskiller/bitbucket-helper

---


# Bitbucket Helper

Auto-detects from git remote: `bitbucket.org` → Cloud, else → Server.

The helper script lives at `scripts/bitbucket_server_pr.py` relative to this skill's directory (the harness resolves it). Run it from the user's repo with the script's absolute or skill-relative path:

```bash
python3 <skill-dir>/scripts/bitbucket_server_pr.py
```

## Steps

1. Run helper with no args to detect type and PR context. Done when source, target, project, repo known.
2. PR body needed: use `/pr-writing` first. Done when body has Description, Test Plan, Test Result, Code Risk, Links.
3. Before live create/update/approve: confirm unless user explicitly asked.
4. For review: start with `review-context`, then targeted `diff --path` or `file`.
5. For updates: read PR version first, send only mutable fields (title, description, version, fromRef, toRef, reviewers). Never send `author`.

Completion: operation scoped to detected repo and PR, mutations authorized.

## Commands

```bash
# Read
get <pr_id> --repo-dir . [--body]
review-context <pr_id> --repo-dir .
files <pr_id> --repo-dir .
diff <pr_id> --repo-dir . --path <path>
file <path> --repo-dir . --at refs/heads/main
commits <pr_id> --repo-dir .
commit <sha> --repo-dir .

# Mutate
approve <pr_id> --repo-dir .
create --repo-dir . --target main --title "PROJ-123: title" [--draft]
update <pr_id> --repo-dir . [--refresh-description | --ready]
```

Flags: `--full`, `--body`, `--format text`, `--cloud`, `--base-url`.

## Auth

`BB_USER` / `BB_PASSWORD` or scoped: `BB_CLOUD_*` / `BB_SERVER_*` (scoped win). Cloud: App Password with Repositories and Pull Requests Read/Write.

## Detection

| Remote | Type |
|---|---|
| `bitbucket.org` in URL | Cloud |
| `host/scm/` or `host/projects/` | Server |

Override: `--cloud` or `--base-url`.