aiskillstore/bitbucket-devops

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 client library.

Key Advantage: Uses direct Node.js calls (auto-approved) instead of MCP tools, eliminating the approval prompts issue from GitHub Issue #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:

node ~/.claude/skills/bitbucket-devops/lib/helpers.js <command> <args>

Example:

# 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 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:

node ~/.claude/skills/bitbucket-devops/bitbucket-mcp/dist/index-cli.js <command> <args>

You MAY chain multiple Tier 2 commands - see 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

{
  "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 for details on credential requirements.

---

Quick Start: Essential Patterns

Pattern 0: Always Detect Workspace and Repository First

Before any pipeline operation, determine the workspace and repository.

Auto-detect from git remote:

git_url=$(git config --get remote.origin.url 2>/dev/null)
if [[ "$git_url" =~ bitbucket.org[:/]([^/]+)/([^/.]+) ]]; then
  WORKSPACE="${BASH_REMATCH[1]}"
  REPO="${BASH_REMATCH[2]}"
  echo "Detected: $WORKSPACE/$REPO"
fi

Or ask user: "What's your Bitbucket workspace and repository name?"

IMPORTANT: Use actual values in commands. Never use literal strings "workspace" or "repo".

Pattern 1: Find Latest Failing Pipeline

node ~/.claude/skills/bitbucket-devops/lib/helpers.js \
  get-latest-failed "workspace" "repo"

Present to user:

Latest failed pipeline:
- Pipeline #123
- Branch: main
- Commit: abc123d - "Fix bug in deployment"
- Status: FAILED

Pattern 2: Download Logs for Failed Pipeline

# Step 1: Get pipeline by build number
node ~/.claude/skills/bitbucket-devops/lib/helpers.js \
  get-by-number "workspace" "repo" 123

# Step 2: Download all failed step logs
node ~/.claude/skills/bitbucket-devops/lib/helpers.js \
  download-failed-logs "workspace" "repo" "{pipeline-uuid}" 123

Present to user:

Downloaded logs for 2 failed steps:

1. Deploy
   - Saved to: .pipeline-logs/pipeline-123-Deploy.log
   - Size: 12.4 KB

2. Integration_Tests
   - Saved to: .pipeline-logs/pipeline-123-Integration_Tests.log
   - Size: 45.2 KB

Important: Check log file size before displaying. If > 50KB, show summary only:

tail -n 100 .pipeline-logs/pipeline-123-Deploy.log
grep -i "error\|failed\|exception" .pipeline-logs/pipeline-123-Deploy.log

Pattern 3: The DevOps REPL Loop (Full Debugging Workflow)

User: "Fix the failing build"

1. READ - Find and Analyze Failure:

node ~/.claude/skills/bitbucket-devops/lib/helpers.js get-latest-failed "workspace" "repo"
node ~/.claude/skills/bitbucket-devops/lib/helpers.js get-failed-steps "workspace" "repo" "{uuid}"
node ~/.claude/skills/bitbucket-devops/lib/helpers.js download-failed-logs "workspace" "repo" "{uuid}" 123

2. EVAL - Analyze the Logs:

grep -i "error\|failed\|exception\|fatal" .pipeline-logs/*.log
grep -i -A 5 -B 5 "error" .pipeline-logs/pipeline-*.log

3. PRINT - Suggest Fix:

Found the issue in Pipeline #123:

Error Type: TypeScript compilation error
Location: src/auth/service.ts:42
Error: Property 'userId' does not exist on type 'User'

Root Cause: The User interface was updated but this file wasn't

Suggested Fix:
Change line 42 from:
  return user.userId
To:
  return user.id

Should I apply this fix?

4. LOOP - Apply Fix and Re-Test:

# Apply fix using Edit tool
# Commit changes
git add src/auth/service.ts
git commit -m "Fix: Update User property reference from userId to id"

# Trigger new pipeline run
node ~/.claude/skills/bitbucket-devops/bitbucket-mcp/dist/index-cli.js \
  run-pipeline "workspace" "repo" "branch-name"

# Monitor the new build
node ~/.claude/skills/bitbucket-devops/lib/helpers.js get-by-number "workspace" "repo" <new-build-number>

5. REPEAT or CELEBRATE:

• If new build FAILS: Go back to step 1 with new logs
• If new build SUCCEEDS: ✅ Success! Build is green
• If new build IN_PROGRESS: Monitor with Pattern 9

This transforms hours of manual debugging into minutes of AI-assisted iteration.

---

Complete Documentation

For comprehensive coverage, refer to these detailed guides:

• docs/REFERENCE.md - Complete command reference for all Tier 1, 2, and 3 operations
• docs/PATTERNS.md - All 11 usage patterns with detailed examples and bash scripts
• docs/TROUBLESHOOTING.md - Common errors, diagnostic commands, and solutions
• docs/GIT_OPERATIONS.md - Credential requirements for API vs git operations

---

Log Storage

Logs are downloaded to .pipeline-logs/ in the directory where VSCode is opened (your working directory).

Structure:

/path/to/open-project/
├── .pipeline-logs/           ← Created automatically here
│   ├── pipeline-123-Deploy.log
│   ├── pipeline-123-Test.log
│   └── errors-only.txt
├── src/
└── ...

Important:

• Logs are stored in the current working directory
• Always use relative path: .pipeline-logs/filename.log
• Tell user to add .pipeline-logs/ to their project's .gitignore
• Logs persist across sessions for easy reference

---

Common Errors (Quick Reference)

| Error | Cause | Solution | |-------|-------|----------| | "Pipeline not found" | Build number too old | Use get-latest-failed instead | | "Logs unavailable" | Pipeline still running | Wait for completion | | "No credential file found" | Missing credentials.json | Copy from credentials.json.template | | "Node.js not found" | Node not installed | Install Node.js v18+ | | "Submodule not initialized" | Git submodule missing | Run bash install.sh | | "401 Unauthorized" | Wrong credentials | Check user_email (not username) in credentials.json | | "Git auth failed" | Wrong username | Check username (not email) for git operations |

For detailed troubleshooting: See docs/TROUBLESHOOTING.md

---

Best Practices

1. Always confirm workspace/repo - Auto-detect from git or ask user
2. Check pipeline status before logs - Don't request logs for running pipelines
3. Limit initial results - Start with 10 recent pipelines, increase if needed
4. Smart log filtering - Use grep to find errors first
5. Cache results - Store JSON responses in variables to avoid redundant calls
6. Use helper functions - Prefer Tier 1 helpers for common operations

---

Performance Notes

• No approval prompts: Bash tool with node commands is auto-approved
• Direct API calls: No MCP protocol overhead
• Credential caching: Loaded once per invocation
• Bitbucket rate limits: 60 requests/hour per user (standard tier)

---

Credits

This skill is built on bitbucket-mcp by Apra Labs, forked from @MatanYemini's original work.

Architecture: Uses bitbucket-mcp as a library (git submodule), NOT as an MCP server. This approach eliminates approval prompts while maintaining full API functionality.

License: CC BY 4.0 Maintained by: Apra Labs