bitbucket
π―SkillInstallation
npx skills add g1joshi/agent-skills --skill bitbucketRun it in a terminal; it asks which AI coding tools to install it for (Claude Code, Codex, Cursor and more).
Uses skills.sh Β· Node.js 22.20+
After installing
Ask for related work and the agent uses it on its own, or call it yourself.
/bitbucketInstall by hand
Copy the whole skill folder from GitHub to the place below. Copying only SKILL.md can leave out files the skill uses.
Open the skill folder β- This project
.claude/skills/bitbucket/ - All projects
~/.claude/skills/bitbucket/
These paths are for Claude Code. For other tools, the command above puts it in the right place.
SKILL.md
View on GitHub βExpert Atlassian Bitbucket assistance covering Bitbucket Pipelines, pull requests, branch permissions, and Jira integration. Use when managing repositories and CI/CD workflows on Bitbucket Cloud/Server.
Bitbucket
Bitbucket is Atlassian's Git solution. Its superpower is Jira Integration.
When to Use
- Enterprise Git Hosting with Atlassian Ecosystem: Tightly integrated Git repositories with Jira Software and Confluence.
- Bitbucket Pipelines (CI/CD): Cloud-native CI/CD defined in
bitbucket-pipelines.ymlwithout external build servers. - Branch Permissions & Merge Checks: Enforcing minimum approvals, successful builds, and resolved tasks before merging.
- Bitbucket Cloud REST API v2: Automating repository provisioning, PR management, and user permissions.
Quick Start
# bitbucket-pipelines.yml
image: node:20
pipelines:
default:
- step:
name: Build and Test
caches:
- node
script:
- npm ci
- npm test
Core Concepts
Declarative CI/CD Pipeline (bitbucket-pipelines.yml)
Automating test, build, and deployment pipelines:
# bitbucket-pipelines.yml
image: node:22-alpine
pipelines:
default:
- step:
name: Lint and Unit Tests
caches:
- node
script:
- npm ci
- npm run lint
- npm test -- --coverage
branches:
main:
- step:
name: Build and Push Container
services:
- docker
caches:
- docker
script:
- export IMAGE_TAG=$BITBUCKET_COMMIT
- docker build -t myregistry.com/app:$IMAGE_TAG .
- echo "$REGISTRY_PASSWORD" | docker login -u "$REGISTRY_USER" --password-stdin myregistry.com
- docker push myregistry.com/app:$IMAGE_TAG
- step:
name: Deploy to Production
deployment: production
trigger: manual # Requires manual approval in UI
script:
- echo "Deploying version $BITBUCKET_COMMIT to production..."
Bitbucket REST API v2 Operations with Curl
Querying pull requests and triggering builds programmatically:
# Fetch open pull requests using personal access token
curl -s -X GET \
-H "Authorization: Bearer $BITBUCKET_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
"https://api.bitbucket.org/2.0/repositories/my-workspace/my-repo/pullrequests?state=OPEN" | jq .
Jira Smart Commits Integration
Transitioning Jira issues and logging time via Git commit messages:
# Commit message format: <Issue-Key> #<command> [optional comments]
git commit -m "PROJ-1029 #resolve Added rate limiting to billing endpoint"
git commit -m "PROJ-1029 #time 2h 30m #comment Refactored token validation"
Common Patterns
Deployment Environments with Manual Approval Gates
Problem: Continuous delivery deploying to production before QA review.
Solution: Use Bitbucket environment triggers with manual gates:
pipelines:
branches:
main:
- step:
name: Test & Build
script:
- npm test
- step:
name: Deploy to Staging
deployment: staging
script:
- ./deploy-staging.sh
- step:
name: Deploy to Production
trigger: manual
deployment: production
script:
- ./deploy-prod.sh
Best Practices
Do:
- Configure Merge Checks to require successful pipeline builds and minimum reviewer approvals on protected branches.
- Use Repository Variables (masked and secured) for cloud API credentials and deployment tokens.
- Use
deployment: productionsteps to track deployment history and rollback status in Jira. - Leverage Bitbucket Pipeline caches (
caches: - node,- docker) to accelerate build execution.
Don't:
- Allow force-pushing (
git push --force) tomainor release branches. - Store plaintext passwords or tokens in
bitbucket-pipelines.yml. - Run long deployment steps without explicit
trigger: manualon production environments.
Troubleshooting
| Error | Cause | Solution |
|---|---|---|
Configuration error in bitbucket-pipelines.yml | Invalid YAML indentation or unsupported pipeline keyword. | Validate syntax using Bitbucket Pipelines Validator tool. |
Pipeline build step timed out after 120 minutes | Long-running test or hanging process exceeded timeout. | Add max-time: 30 to step configuration and inspect logs. |
Permission denied (publickey) on git clone in pipeline | SSH key not added to Bitbucket Repository Settings > Access Keys. | Generate SSH key pair in Pipeline Settings and register public key. |
References
More from this repository10
A template skill providing a starter framework for creating new agent skills with structured sections for triggers, quick start examples, and capability descriptions.
Skill
Skill
Skill
Skill
Skill
Skill
Skill
Skill
Skill