bitbucket-devops

What this skill does

# Bitbucket DevOps Skill

This skill provides comprehensive Bitbucket DevOps automation using direct Node.js API calls via the Bash tool. Built on the [bitbucket-mcp](https://github.com/Apra-Labs/bitbucket-mcp) client library.

**Key Advantage:** Uses direct Node.js calls (auto-approved) instead of MCP tools, eliminating the approval prompts issue from [GitHub Issue #10801](https://github.com/anthropics/claude-code/issues/10801).

## ⚠️ MANDATORY: How to Approach User Requests

**You MUST follow this three-tier fallback strategy for ALL Bitbucket operations. This is REQUIRED, not optional.**

**CRITICAL RULES:**
- **DO NOT create new .js files for Bitbucket API calls**
- **DO NOT use `node -e` for inline Bitbucket API operations**
- **ONLY use the pre-built CLI tools listed below**
- **ALWAYS start with Tier 1, fall back to Tier 2 if needed, use Tier 3 only as last resort**

### Tier 1: High-Level Helper Functions (REQUIRED FIRST STEP)

**You MUST check these helpers FIRST before attempting any other approach.**

These solve common workflows in a single command. If the user's request matches any of these patterns, you MUST use the corresponding helper.

**Location:** `~/.claude/skills/bitbucket-devops/lib/helpers.js`

**Available Commands:**
- `get-latest-failed <workspace> <repo>` - Get most recent failed pipeline
- `get-latest <workspace> <repo>` - Get most recent pipeline (any status)
- `get-by-number <workspace> <repo> <build-number>` - Find pipeline by build number
- `get-failed-steps <workspace> <repo> <pipeline-uuid>` - Get all failed steps
- `download-failed-logs <workspace> <repo> <pipeline-uuid> <build-number>` - Download all failed step logs
- `get-info <workspace> <repo> <pipeline-uuid>` - Get formatted pipeline + steps info

**MUST use for:** "latest failed build", "download logs for pipeline #123", "what failed in this build", "get pipeline by number"

**Usage:**
```bash
node ~/.claude/skills/bitbucket-devops/lib/helpers.js <command> <args>
```

**Example:**
```bash
# User: "What's the latest failing pipeline?"
# You MUST use:
node ~/.claude/skills/bitbucket-devops/lib/helpers.js get-latest-failed "workspace" "repo"

# DO NOT create a new script
# DO NOT use node -e
# DO NOT write custom API calls
```

### Tier 2: Low-Level CLI Commands (IF TIER 1 CANNOT SOLVE)

**ONLY use Tier 2 if NO Tier 1 helper matches the user's request.**

Direct API wrappers for specific operations. You MUST use these for operations not covered by Tier 1 helpers.

**Location:** `~/.claude/skills/bitbucket-devops/bitbucket-mcp/dist/index-cli.js`

**Key Commands** (see [docs/REFERENCE.md](docs/REFERENCE.md) for complete list):

**Pipeline Operations:**
- `list-pipelines <workspace> <repo> [limit]`
- `get-pipeline <workspace> <repo> <pipeline-uuid>`
- `get-pipeline-steps <workspace> <repo> <pipeline-uuid>`
- `get-step-logs <workspace> <repo> <pipeline-uuid> <step-uuid>`
- `run-pipeline <workspace> <repo> <branch> [pipeline-name] [variables-json]`
- `stop-pipeline <workspace> <repo> <pipeline-uuid>`

**Pull Request Operations:**
- `list-prs <workspace> <repo> [state] [limit]`
- `get-pr <workspace> <repo> <pr_id>`
- `approve-pr <workspace> <repo> <pr_id>`
- `merge-pr <workspace> <repo> <pr_id> [message] [strategy]`
- `decline-pr <workspace> <repo> <pr_id> [message]`

**Repository Operations:**
- `get-branching-model <workspace> <repo>`
- `list-repositories <workspace>`

**Usage:**
```bash
node ~/.claude/skills/bitbucket-devops/bitbucket-mcp/dist/index-cli.js <command> <args>
```

**You MAY chain multiple Tier 2 commands** - see [docs/PATTERNS.md](docs/PATTERNS.md) for examples.

### Tier 3: Direct Bitbucket API Calls (ONLY IF TIER 1 AND 2 FAIL)

**ONLY use Tier 3 if BOTH Tier 1 AND Tier 2 cannot solve the request. This should be RARE.**

Before using Tier 3, you MUST:
1. Verify no Tier 1 helper exists
2. Verify no Tier 2 CLI command exists
3. Verify no combination of Tier 1 + Tier 2 can solve it

**Documentation:** `~/.claude/skills/bitbucket-devops/bitbucket-mcp/docs/`
- `api-overview.md` - Authentication, base URLs, rate limits
- `pipelines-api.md` - Complete pipeline API reference
- `repositories-api.md` - Repository operations
- `pull-requests-api.md` - PR operations (future)

---

## REQUIRED Decision Process

**Before performing ANY Bitbucket operation, you MUST:**

1. **Check Tier 1 helpers** - Review the 6 helpers above. Does one solve this?
   - **YES** → Use it immediately with `node ~/.claude/skills/bitbucket-devops/lib/helpers.js <command>`
   - **NO** → Continue to step 2

2. **Check Tier 2 CLI** - Review the CLI commands above. Can one or more solve this?
   - **YES** → Use them with `node ~/.claude/skills/bitbucket-devops/bitbucket-mcp/dist/index-cli.js <command>`
   - **NO** → Continue to step 3

3. **Check Tier 3 docs** - Read API docs. Is there a direct API call needed?
   - **YES** → Read docs, use curl with credentials
   - **NO** → Ask user for clarification

**NEVER skip this process. NEVER create new .js files. ALWAYS use pre-built tools.**

---

## Known Limitations

### Pipeline Artifacts Cannot Be Downloaded via API

**IMPORTANT:** Bitbucket Cloud does NOT provide an API to download pipeline artifacts.

**If a user asks to download build artifacts:**
1. Inform them that artifact download via API is not possible
2. Direct them to the Bitbucket web UI:
   - Repository → Pipelines → Build # → Step → Artifacts section → Download button
3. Note: Artifacts expire automatically after 14 days

**Tip:** For programmatic artifact access, consider uploading to S3/Azure Blob Storage during your pipeline.

**DO NOT:** Search for undocumented endpoints - this has been thoroughly researched and no API exists.

---

## The DevOps REPL Advantage

Traditional pipeline debugging is slow: push code → wait → fail → investigate logs → fix → repeat (hours per cycle).

This skill enables a **REPL-like experience for DevOps**: Claude observes pipelines in real-time, analyzes failures instantly, suggests precise fixes, and iterates with you until builds pass - reducing debugging cycles from hours to minutes.

**The Loop:**
1. **Read**: Monitor pipeline execution and capture failures
2. **Eval**: AI analyzes logs and identifies root cause
3. **Print**: Claude presents findings and suggests fixes
4. **Loop**: Apply fix, trigger build, repeat until green ✅

This transforms DevOps from slow batch processing into interactive, conversational development.

---

## Prerequisites

This skill uses the Bash tool (auto-approved in Claude Code) to run Node.js commands. Required:
- Node.js (v18+)
- Git (for submodule management)

**Note:** No MCP server required - bitbucket-mcp is used as a library via git submodule.

---

## Configuration

The skill directory is located at: `~/.claude/skills/bitbucket-devops/`

Credentials are loaded with priority (first found wins):
1. **Project level**: `./credentials.json` or `./.bitbucket-credentials` (current working directory)
2. **User level**: `~/.bitbucket-credentials` (home directory)
3. **Skill level**: `~/.claude/skills/bitbucket-devops/credentials.json`

### Credential Format

**IMPORTANT: Different credentials for different operations**

```json
{
  "url": "https://api.bitbucket.org/2.0",
  "workspace": "your-workspace-name",
  "user_email": "[email protected]",
  "username": "your-workspace-name",
  "password": "your-bitbucket-app-password"
}
```

**Field explanations:**
- `user_email`: Your Bitbucket account email (for API authentication) - MUST contain `@`
- `username`: Your Bitbucket workspace slug (for git operations) - MUST NOT contain `@`
- `password`: App password from https://bitbucket.org/account/settings/app-passwords/
  - Required permissions: Repositories: Read, Pipelines: Read

See [docs/GIT_OPERATIONS.md](docs/GIT_OPERATIONS.md) for details on credential requirements.

---

## Quick Start: Essential Patterns

### Pattern 0: Always Detect Workspace and Repository First

**Before any pipeline operation**, determ