# atlassian-bitbucket-by-altf1be

Adopt this skill: https://proskills.md/skills/other/alt-f1-openclaw-openclaw-skill-atlassian-bitbucket-by-altf1be

Page: https://proskills.md/skills/other/alt-f1-openclaw-openclaw-skill-atlassian-bitbucket-by-altf1be
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 8005
upstream: https://github.com/alt-f1-openclaw/openclaw-skill-atlassian-bitbucket-by-altf1be/blob/HEAD/SKILL.md

````text
---
name: atlassian-bitbucket-by-altf1be
description: "Atlassian Bitbucket Cloud skill — full CRUD on repos, PRs, pipelines, issues, snippets, workspaces, branches, deployments, and more via Bitbucket REST API 2.0 with API Token auth."
homepage: https://github.com/ALT-F1-OpenClaw/openclaw-skill-atlassian-bitbucket-by-altf1be
metadata:
  {"openclaw": {"emoji": "🪣", "requires": {"env": ["BITBUCKET_EMAIL", "BITBUCKET_API_TOKEN"]}, "optional": {"env": ["BITBUCKET_WORKSPACE", "BITBUCKET_MAX_RESULTS", "BITBUCKET_USERNAME", "BITBUCKET_APP_PASSWORD"]}, "primaryEnv": "BITBUCKET_EMAIL"}}
---

# Atlassian Bitbucket Cloud by @altf1be

Full CRUD on repos, PRs, pipelines, issues, snippets, workspaces, branches, deployments, and more via Bitbucket REST API 2.0.

## Setup

1. Create an **API Token** at https://id.atlassian.com/manage-profile/security/api-tokens (select the scopes you need).
2. Set environment variables (or create `.env` in `{baseDir}`):

```
# Required
BITBUCKET_EMAIL=you@example.com
BITBUCKET_API_TOKEN=your-api-token

# Optional
BITBUCKET_WORKSPACE=your-default-workspace
BITBUCKET_MAX_RESULTS=50

# Legacy (supported until June 9, 2026)
# BITBUCKET_USERNAME=your-username
# BITBUCKET_APP_PASSWORD=your-app-password
```

3. Install dependencies: `cd {baseDir} && npm install`

## Common Options

Most commands accept these shared flags:

| Flag | Description |
|---|---|
| `-w, --workspace <slug>` | Workspace slug (or set `BITBUCKET_WORKSPACE`) |
| `-r, --repo <slug>` | Repository slug |
| `--pagelen <n>` | Results per page |
| `--page <n>` | Page number |
| `--all` | Fetch all pages |
| `-q, --q <filter>` | Filter query (CQL-style) |
| `--sort <field>` | Sort field |
| `--confirm` | Required for all delete operations |
| `--data <json>` | Raw JSON body for complex payloads |

## Commands

### 1. Repositories (26 commands)

CRUD on repositories, forks, watchers, webhooks, override settings, and permissions.

| Command | Description |
|---|---|
| `repo-list-public` | List all public repositories |
| `repo-list` | List repositories in a workspace |
| `repo-get` | Get repository details |
| `repo-create` | Create a new repository |
| `repo-update` | Update repository settings |
| `repo-delete` | Delete a repository |
| `repo-forks` | List forks of a repository |
| `repo-fork-create` | Fork a repository |
| `repo-watchers` | List repository watchers |
| `hook-list` | List repository webhooks |
| `hook-get` | Get a webhook by UID |
| `hook-create` | Create a repository webhook |
| `hook-update` | Update a webhook |
| `hook-delete` | Delete a webhook |
| `repo-override-settings-get` | Get repository override settings |
| `repo-override-settings-update` | Update repository override settings |
| `repo-group-permission-list` | List group permissions |
| `repo-group-permission-get` | Get a group's permission |
| `repo-group-permission-update` | Update a group's permission |
| `repo-group-permission-delete` | Remove a group's permission |
| `repo-user-permission-list` | List user permissions |
| `repo-user-permission-get` | Get a user's permission |
| `repo-user-permission-update` | Update a user's permission |
| `repo-user-permission-delete` | Remove a user's permission |
| `user-repo-permissions` | List current user's repository permissions |
| `user-ws-repo-permissions` | List current user's repository permissions in a workspace |

```bash
# List repos in a workspace
bitbucket repo-list -w myworkspace

# Get repo details
bitbucket repo-get -w myworkspace -r my-repo

# Create a new private repo
bitbucket repo-create -w myworkspace -r new-repo --is-private true --scm git

# Fork a repo
bitbucket repo-fork-create -w myworkspace -r upstream-repo --data '{"name":"my-fork"}'

# Create a webhook
bitbucket hook-create -w myworkspace -r my-repo --url https://example.com/hook --events repo:push

# Delete a repo (requires --confirm)
bitbucket repo-delete -w myworkspace -r old-repo --confirm
```

### 2. Pull Requests (36 commands)

Full lifecycle management of pull requests: create, review, approve, merge, comment, tasks, and default reviewers.

| Command | Description |
|---|---|
| `pr-list` | List pull requests |
| `pr-create` | Create a pull request |
| `pr-get` | Get a pull request by ID |
| `pr-update` | Update a pull request |
| `pr-activity` | Get PR activity log |
| `pr-approve` | Approve a pull request |
| `pr-unapprove` | Remove approval from a PR |
| `pr-comments` | List PR comments |
| `pr-comment-create` | Add a comment to a PR |
| `pr-comment-get` | Get a specific PR comment |
| `pr-comment-update` | Update a PR comment |
| `pr-comment-delete` | Delete a PR comment |
| `pr-comment-resolve` | Resolve a PR comment thread |
| `pr-comment-reopen` | Reopen a resolved comment thread |
| `pr-commits` | List commits in a PR |
| `pr-decline` | Decline a pull request |
| `pr-diff` | Get the diff of a PR |
| `pr-diffstat` | Get the diffstat of a PR |
| `pr-merge` | Merge a pull request |
| `pr-merge-task-status` | Check merge task status |
| `pr-patch` | Get the patch of a PR |
| `pr-request-changes` | Request changes on a PR |
| `pr-unrequest-changes` | Remove change request from a PR |
| `pr-statuses` | List commit statuses on a PR |
| `pr-tasks` | List tasks on a PR |
| `pr-task-create` | Create a task on a PR |
| `pr-task-get` | Get a specific PR task |
| `pr-task-update` | Update a PR task |
| `pr-task-delete` | Delete a PR task |
| `default-reviewer-list` | List default reviewers |
| `default-reviewer-get` | Get a default reviewer |
| `default-reviewer-add` | Add a default reviewer |
| `default-reviewer-delete` | Remove a default reviewer |
| `effective-default-reviewers` | List effective default reviewers |
| `pr-for-commit` | Find PRs containing a commit |
| `pr-activity-all` | Get activity across all PRs in a repo |

```bash
# List open PRs
bitbucket pr-list -w myworkspace -r my-repo -q 'state="OPEN"'

# Create a PR
bitbucket pr-create -w myworkspace -r my-repo --title "Add feature" \
  --source feature-branch --destination main

# Approve a PR
bitbucket pr-approve -w myworkspace -r my-repo --pr-id 42

# Merge a PR
bitbucket pr-merge -w myworkspace -r my-repo --pr-id 42 --merge-strategy squash

# Add a comment
bitbucket pr-comment-create -w myworkspace -r my-repo --pr-id 42 \
  --body "Looks good to me!"

# Create a task on a PR
bitbucket pr-task-create -w myworkspace -r my-repo --pr-id 42 \
  --data '{"content":{"raw":"Fix the typo on line 10"}}'

# Find PRs for a commit
bitbucket pr-for-commit -w myworkspace -r my-repo --commit abc123
```

### 3. Commits (16 commands)

Read commit details, approve/unapprove commits, manage commit comments, list diffs and patches.

| Command | Description |
|---|---|
| `commit-get` | Get a specific commit |
| `commit-approve` | Approve a commit |
| `commit-unapprove` | Remove commit approval |
| `commit-comments` | List comments on a commit |
| `commit-comment-create` | Add a comment to a commit |
| `commit-comment-get` | Get a specific commit comment |
| `commit-comment-update` | Update a commit comment |
| `commit-comment-delete` | Delete a commit comment |
| `commit-list` | List commits (GET) |
| `commit-list-post` | List commits (POST, with body filters) |
| `commit-list-revision` | List commits from a revision (GET) |
| `commit-list-revision-post` | List commits from a revision (POST) |
| `diff` | Get diff between two refs |
| `diffstat` | Get diffstat between two refs |
| `merge-base` | Get merge base of two refs |
| `patch` | Get patch for a revision |

```bash
# Get commit details
bitbucket commit-get -w myworkspace -r my-repo --commit abc123def

# List recent commits
bitbucket commit-list -w myworkspace -r my-repo --pagelen 10

# Get diff between two refs
bitbucket diff -w myworkspace -r my-repo --spec "main..feature-branch"

# Approve a commit
bitbucket commit-approve -w myworkspace -r my-repo --commit abc123def

# Comment on a commit
bitbucket commit-comment-create -w myworkspace -r my-repo --commit abc123def \
  --
````

## File: README.md
upstream: https://github.com/alt-f1-openclaw/openclaw-skill-atlassian-bitbucket-by-altf1be/blob/HEAD/README.md

````text
# :bucket: openclaw-skill-atlassian-bitbucket-by-altf1be

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green.svg)](https://nodejs.org/)
[![Bitbucket Cloud](https://img.shields.io/badge/Bitbucket_Cloud-API_2.0-blue.svg)](https://developer.atlassian.com/cloud/bitbucket/rest/intro/)
[![OpenClaw Skill](https://img.shields.io/badge/OpenClaw-Skill-orange.svg)](https://clawhub.ai)
[![ClawHub](https://img.shields.io/badge/ClawHub-atlassian--bitbucket--by--altf1be-blueviolet.svg)](https://clawhub.ai/skills/atlassian-bitbucket-by-altf1be)
[![GitHub last commit](https://img.shields.io/github/last-commit/ALT-F1-OpenClaw/openclaw-skill-atlassian-bitbucket-by-altf1be)](https://github.com/ALT-F1-OpenClaw/openclaw-skill-atlassian-bitbucket-by-altf1be/commits/main)
[![GitHub issues](https://img.shields.io/github/issues/ALT-F1-OpenClaw/openclaw-skill-atlassian-bitbucket-by-altf1be)](https://github.com/ALT-F1-OpenClaw/openclaw-skill-atlassian-bitbucket-by-altf1be/issues)
[![GitHub stars](https://img.shields.io/github/stars/ALT-F1-OpenClaw/openclaw-skill-atlassian-bitbucket-by-altf1be)](https://github.com/ALT-F1-OpenClaw/openclaw-skill-atlassian-bitbucket-by-altf1be/stargazers)

OpenClaw skill for Atlassian Bitbucket Cloud — full CRUD via REST API 2.0

By [Abdelkrim BOUJRAF](https://www.alt-f1.be) / ALT-F1 SRL, Brussels

## Table of Contents

- [Features](#features)
- [Quick Start](#quick-start)
- [API Groups](#api-groups)
- [Authentication](#authentication)
- [Common Options](#common-options)
- [Environment Variables](#environment-variables)
- [Security](#security)
- [License](#license)
- [Author](#author)
- [Links](#links)

## Features

- **335 API endpoints** covering the entire Bitbucket Cloud REST API 2.0
- **23 API groups** — repositories, pull requests, pipelines, issues, and more
- **App Password authentication** — simple, secure, no OAuth flow required
- **Rate-limit retry** with exponential backoff (up to 3 attempts)
- **Pagination support** for all list operations
- **JSON output** for easy integration with other tools and scripts
- **Delete safety** — all destructive operations require explicit `--confirm`
- **Path traversal prevention** for file uploads
- **File size validation** before upload (50 MB default limit)

## Quick Start

```bash
# 1. Clone the repository
git clone https://github.com/ALT-F1-OpenClaw/openclaw-skill-atlassian-bitbucket-by-altf1be.git
cd openclaw-skill-atlassian-bitbucket-by-altf1be

# 2. Install dependencies
npm install

# 3. Configure environment
cp .env.example .env
# Edit .env with your Bitbucket credentials:
#   BITBUCKET_EMAIL=you@example.com
#   BITBUCKET_API_TOKEN=your-api-token
#   BITBUCKET_WORKSPACE=your-workspace

# 4. Run commands
node scripts/bitbucket.mjs repo-list --workspace my-workspace
node scripts/bitbucket.mjs repo-read --workspace my-workspace --repo my-repo
node scripts/bitbucket.mjs pr-list --workspace my-workspace --repo my-repo
node scripts/bitbucket.mjs pipeline-list --workspace my-workspace --repo my-repo
```

## API Groups

All 335 endpoints organized across 23 API groups:

| # | API Group | Endpoints |
|---|-----------|-----------|
| 1 | Addon | 10 |
| 2 | Branch restrictions | 5 |
| 3 | Branching model | 7 |
| 4 | Commit statuses | 4 |
| 5 | Commits | 16 |
| 6 | Deployments | 16 |
| 7 | Downloads | 4 |
| 8 | GPG | 4 |
| 9 | Issue tracker | 33 |
| 10 | Pipelines | 68 |
| 11 | Projects | 16 |
| 12 | Properties | 12 |
| 13 | Pullrequests | 36 |
| 14 | Refs | 9 |
| 15 | Reports | 9 |
| 16 | Repositories | 26 |
| 17 | Search | 3 |
| 18 | Snippets | 25 |
| 19 | Source | 4 |
| 20 | SSH | 5 |
| 21 | Users | 4 |
| 22 | Webhooks | 2 |
| 23 | Workspaces | 17 |

See [docs/API-COVERAGE.md](./docs/API-COVERAGE.md) for a full breakdown of every endpoint.

## Authentication

This skill uses **Atlassian API Tokens** for authentication (App Passwords were deprecated in September 2025 and will be disabled on June 9, 2026).

### Creating an API Token

#### Step 1 — Open the API Tokens page

Log in to your Atlassian account and go to **[Security → API tokens](https://id.atlassian.com/manage-profile/security/api-tokens)**.

Click **"Create API token with scopes"** (the blue outlined button) to create a scoped token for Bitbucket.

![API Tokens overview](./docs/images/01-api-tokens-overview.png)

#### Step 2 — Name and expiry

Give the token a descriptive name (e.g., `openclaw-skill-atlassian-bitbucket-by-altf1be-2026-04-03`) and set an expiration date (max 365 days). Click **Next**.

![Name and expiry](./docs/images/02-name-and-expiry.png)

#### Step 3 — Select the app

Select **Bitbucket** as the API token app. This ensures the token can only access Bitbucket APIs and perform git operations. Click **Next**.

![Select app — Bitbucket](./docs/images/03-select-app-bitbucket.png)

#### Step 4 — Select scopes

Use the **"Scope actions"** filter to select the scope categories you need. For full CRUD access, select: **Admin**, **Read**, **Write**, and **Manage**.

![Select scopes — filter](./docs/images/04-select-scopes-filter.png)

Review the individual scopes. The red arrows below highlight scopes intentionally **left unchecked** for security:
- `write:gpg-key:bitbucket` — Modify GPG keys
- `write:ssh-key:bitbucket` — Modify SSH keys
- `write:user:bitbucket` — Modify user info

![Select scopes — detail](./docs/images/05-select-scopes-detail.png)

#### Step 5 — Review and create

Review the token summary: name, expiry, app, and all selected scopes. Once satisfied, click **"Create token"**.

![Review token](./docs/images/06-review-token.png)

#### Step 6 — Copy the token

**Copy the token immediately** — you won't be able to see it again after closing this dialog. Store it securely (e.g., in a password manager or your `.env` file).

![Copy API token](./docs/images/07-copy-api-token.png)

The skill authenticates using HTTP Basic Auth with your Atlassian email and the API token.

> **Legacy support:** Existing App Passwords (`BITBUCKET_USERNAME` + `BITBUCKET_APP_PASSWORD`) are still accepted as a fallback until June 9, 2026. Migrate to API tokens before then.

## Common Options

| Option | Description |
|--------|-------------|
| `--workspace <slug>` | Bitbucket workspace slug |
| `--repo <slug>` | Repository slug |
| `--id <id>` | Resource identifier |
| `--page <n>` | Page number for paginated results |
| `--pagelen <n>` | Number of results per page (default: 50) |
| `--confirm` | Required flag for delete operations |
| `--help` | Show help for any command |

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `BITBUCKET_EMAIL` | Yes | Your Atlassian account email |
| `BITBUCKET_API_TOKEN` | Yes | API token from [id.atlassian.com](https://id.atlassian.com/manage-profile/security/api-tokens) |
| `BITBUCKET_WORKSPACE` | No | Default workspace slug (avoids passing `--workspace` every time) |
| `BITBUCKET_MAX_RESULTS` | No | Maximum results per page (default: `50`) |
| `BITBUCKET_USERNAME` | Legacy | Bitbucket username (fallback, deprecated June 2026) |
| `BITBUCKET_APP_PASSWORD` | Legacy | App password (fallback, deprecated June 2026) |

Create a `.env` file in the project root or export variables in your shell:

```bash
BITBUCKET_EMAIL=you@example.com
BITBUCKET_API_TOKEN=your-api-token
BITBUCKET_WORKSPACE=your-workspace
```

## Security

- API Token authentication (Basic auth, no OAuth flow needed)
- No secrets or tokens printed to stdout
- All delete operations require explicit `--confirm` flag
- Path traversal prevention for file uploads (`safePath()`)
- Built-in rate limiting with exponential backoff retry (3 attempts)
- File size validation before upload (50 MB limit)
- Lazy config validation (credentials only checked when a command runs)

## License

MIT — see [LICENSE](./LICENSE)

## Author

Abdelkrim BOUJRAF — [ALT-F1 SRL](https://www.alt-f1.be), Brussel
````
