bitbucket-devops

name	bitbucket-devops
description	Comprehensive Bitbucket pipeline automation using direct Node.js API calls. Monitor pipeline status, analyze failures, download logs, and trigger builds. Use this skill when the user asks to check pipeline status, find failing pipelines, download logs, trigger builds, or debug pipeline failures. No MCP approval prompts required - uses Bash tool with node commands.
allowed-tools	Bash, Read, Write, Grep, Glob

Bitbucket DevOps Skill

This skill provides comprehensive Bitbucket DevOps automation using direct Node.js API calls via a Bash-equivalent tool. Built on the bitbucket-mcp client library. It's plain Node.js CLI invocation with no Claude-specific dependency, so it runs unchanged under Claude Code, AGY, OpenCode, or any other agent runtime that can shell out to node.

Note on paths: Paths below (~/.claude/skills/bitbucket-devops/...) reflect Claude Code's skill-install convention, since install.sh/install.ps1 default to --llm claude. If this skill was installed with --llm agy or --llm opencode, substitute ~/.gemini/antigravity-cli/skills/bitbucket-devops/ or ~/.config/opencode/skills/bitbucket-devops/ respectively (or whatever TARGET_DIR was used) - the commands themselves are identical.

Key Advantage: Uses direct Node.js calls via a Bash-equivalent tool instead of MCP tools. This works the same way in any agent runtime that can invoke shell commands (Claude Code, AGY, OpenCode, etc.) - there's no Claude-specific API or tool assumption anywhere in this skill's code. In Claude Code specifically, Bash is auto-approved by default, which also eliminates the MCP approval-prompt friction described in GitHub Issue #10801; other runtimes may have their own approval model for shell commands, but the underlying calls are identical either way.

⚠️ 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
• list-environments <workspace> <repo> - List deployment environments (sandbox/production/etc)
• create-environment <workspace> <repo> <name> [environment_type] [rank] - Create a deployment environment
• list-deploy-variables <workspace> <repo> <environment> - List secured deployment variables for an environment
• create-deploy-variable <workspace> <repo> <environment> <key> <value> [secured] - Add a deployment variable
• update-deploy-variable <workspace> <repo> <environment> <variable> [key] [value] [secured] - Update a deployment variable
• delete-deploy-variable <workspace> <repo> <environment> <variable> - Delete a deployment variable
• check-credentials - Reports which credential file is active and whether it's shaped correctly (field names, format validity), WITHOUT ever printing a secret value. Run this instead of opening/catting a credentials file directly to debug an auth problem.
• check-for-updates - Reports whether this repo's main branch has moved forward since this skill was installed. Report-only, never applies anything.
• self-update [confirm] - Without confirm, same report as check-for-updates. With confirm, pulls/rebuilds the update in place (git checkout installs) or redeploys from a fresh clone (file-copy installs) - never overwrites credentials.json.

MUST use for: "latest failed build", "download logs for pipeline #123", "what failed in this build", "get pipeline by number", "create a sandbox/production deployment environment", "add a deployment secret/variable", "list deployment environments", "check for skill updates", "update this skill"

Requires a different app-password scope than the rest of this skill - see Deployment Environments & Variables below before using these six commands.

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:

• create-pr <workspace> <repo> <title> <source_branch> <target_branch> [description] [reviewers_csv]
• 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.

---

Deployment Environments & Variables (NEW)

Bitbucket Cloud's REST API v2.0 does support creating and managing repository "Deployment environments" (Repository settings → Pipelines → Deployments, e.g. "sandbox", "production") and their secured deployment variables. This was previously undocumented in this skill - it's now available via six new Tier 1 helpers.

Available Commands (node ~/.claude/skills/bitbucket-devops/lib/helpers.js <command> <args>):

• list-environments <workspace> <repo>
• create-environment <workspace> <repo> <name> [environment_type=Test] [rank]
• list-deploy-variables <workspace> <repo> <environment_name_or_uuid>
• create-deploy-variable <workspace> <repo> <environment_name_or_uuid> <key> <value> [secured=true]
• update-deploy-variable <workspace> <repo> <environment_name_or_uuid> <variable_key_or_uuid> [key] [value] [secured]
• delete-deploy-variable <workspace> <repo> <environment_name_or_uuid> <variable_key_or_uuid>

Full details, endpoints, and JSON shapes: docs/REFERENCE.md.

⚠️ Scope Requirements (CONFIRMED empirically, 2026-07)

This skill's originally documented scope (Repositories: Read, Pipelines: Read under the classic app-password model) is NOT enough for the write operations below. Confirmed against a real repo using Atlassian's newer "API token with scopes" credential type (a separate creation flow from the plain/classic API token at https://id.atlassian.com/manage-profile/security/api-tokens -- a classic unscoped token carries zero Bitbucket scopes regardless of account privileges, and fails with "API Token provided has no Bitbucket scopes" if used against Bitbucket's API at all):

Operation	Required scope (Atlassian scoped-token name)	Classic app-password equivalent
list-environments, list-deploy-variables (read)	read:repository:bitbucket	Repositories: Read
pipeline read commands (list-pipelines, get-pipeline*, etc.)	read:pipeline:bitbucket	Pipelines: Read
create-deploy-variable, update-deploy-variable, delete-deploy-variable	write:pipeline:bitbucket -- confirmed sufficient in practice, no separate "edit variables" scope exists in the scoped-token model	Pipelines: Edit variables
create-environment	admin:pipeline:bitbucket -- CONFIRMED via a live 403 response (see below); write:pipeline:bitbucket alone is NOT sufficient	Unclear under the classic model; likely needs Repositories: Admin
create-pr/approve-pr/merge-pr/decline-pr	write:pullrequest:bitbucket	Pull requests: Write

Debugging tip, generalizable to any scope-mismatch: Bitbucket's 403 response for a scope failure is self-diagnosing -- it returns a JSON body with both required and granted scope arrays, e.g.:

{"error":{"message":"Your credentials lack one or more required privilege scopes.","detail":{"required":["admin:pipeline:bitbucket"],"granted":["read:repository:bitbucket","write:pipeline:bitbucket", ...]}}}

Read this directly rather than guessing which scope to add next -- it names the exact missing scope.

Before the write commands above will work, generate an Atlassian API token with scopes (not the plain "Create API token" button, which produces a Bitbucket-incompatible classic token) with the scopes needed for the operations you intend to use, then update your credentials file's password field. Run check-credentials (see below) first to confirm the file shape is valid before testing scope.

⚠️ App Passwords Are Being Retired

Atlassian has an active brownout/deprecation schedule for Bitbucket app passwords, ending in full removal. Before investing in a new app-password scope, check the current status at https://bitbucket.org/account/settings/app-passwords/ and Atlassian's Bitbucket Cloud deprecation announcements - API tokens with scopes (Atlassian account email + scoped API token, still Basic auth) are the forward-compatible replacement and should be used for any credential created or rotated from now on. The credential-loading code in this skill is auth-mechanism agnostic (Basic auth over email:secret), so switching from an app password to an API token is a drop-in credentials-file update, not a code change.

environment_type casing: CONFIRMED

Bitbucket's create-environment endpoint is not in the official API reference, but empirically, title case works: environment_type.name of "Test", "Staging", or "Production" is accepted and echoed back correctly by a real create-environment call and subsequent list-environments reads. Upper-case ("TEST", etc.) has not been tested and title case should be used.

Secured variable values are write-only

Once a variable is created with secured: true (the default for create-deploy-variable), its value is never returned by any subsequent GET/list-deploy-variables call - this matches the Bitbucket web UI's behavior for secrets. update-deploy-variable can replace the value; there is no way to read it back via the API.

---

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: your agent 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. This works the same in Claude Code, AGY, OpenCode, or any other runtime driving this skill.

The Loop:

1. Read: Monitor pipeline execution and capture failures
2. Eval: AI analyzes logs and identifies root cause
3. Print: The agent 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 a Bash-equivalent tool (auto-approved in Claude Code; check your runtime's docs for AGY/OpenCode/others) 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": "[e-mail]",
  "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 for existing (pipeline/PR/repo) commands: Repositories: Read, Pipelines: Read
  • Required permissions for the new deployment environment/variable commands: Pipelines: Edit variables at minimum, likely also Repositories: Admin for create-environment - see Deployment Environments & Variables. Not covered by the scope above - regenerate the app password to add write scopes before using those six commands.
  • Note: app passwords are being deprecated by Atlassian in favor of API tokens - check https://bitbucket.org/account/settings/app-passwords/ for current status before regenerating.

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