--- name: aiskillstore/bitbucket-devops source: https://app.decimal.ai/s/aiskillstore-bitbucket-devops@1/SKILL.md source_sha256: efdacbd4842c --- # 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](https://github.com/Apra-Labs/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](https://github.com/anthropics/claude-code/issues/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 ` - Get most recent failed pipeline - `get-latest ` - Get most recent pipeline (any status) - `get-by-number ` - Find pipeline by build number - `get-failed-steps ` - Get all failed steps - `download-failed-logs ` - Download all failed step logs - `get-info ` - Get formatted pipeline + steps info - `list-environments ` - List deployment environments (sandbox/production/etc) - `create-environment [environment_type] [rank]` - Create a deployment environment - `list-deploy-variables ` - List secured deployment variables for an environment - `create-deploy-variable [secured]` - Add a deployment variable - `update-deploy-variable [key] [value] [secured]` - Update a deployment variable - `delete-deploy-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](#deployment-environments--variables-new) below before using these six commands. **Usage:** ```bash node ~/.claude/skills/bitbucket-devops/lib/helpers.js ``` **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 [limit]` - `get-pipeline ` - `get-pipeline-steps ` - `get-step-logs ` - `run-pipeline [pipeline-name] [variables-json]` - `stop-pipeline ` **Pull Request Operations:** - `create-pr <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:** ```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.** --- ## 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](docs/REFERENCE.md#deployment-environments--variables). ### ⚠️ 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.: ```json {"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** ```json { "url": "https://api.bitbucket.org/2.0", "workspace": "your-workspace-name", "user_email": "your-email@example.com", "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](#deployment-environments--variables-new). 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](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:** ```bash 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 ```bash 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 ```bash # 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: ```bash 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:** ```bash 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:** ```bash 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:** ```bash # 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](docs/REFERENCE.md)** - Complete command reference for all Tier 1, 2, and 3 operations - **[docs/PATTERNS.md](docs/PATTERNS.md)** - All 11 usage patterns with detailed examples and bash scripts - **[docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)** - Common errors, diagnostic commands, and solutions - **[docs/GIT_OPERATIONS.md](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](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](https://github.com/Apra-Labs/bitbucket-mcp) by Apra Labs, forked from [@MatanYemini's original work](https://github.com/MatanYemini/bitbucket-mcp). **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](https://github.com/Apra-Labs)