Bitbucket

Bitbucket CLI Skill

Execute Bitbucket helper functions with proper authentication via OAuth token.

You must source the helpers before use:

source ./_skills/connections/bitbucket/bitbucket/scripts/bitbucket_helpers.sh

CLI Tips

NEVER USE RAW CURL OR DIRECT API CALLS

DO NOT write raw curl/HTTP requests like:

# ❌ WRONG - Never do this
curl -s -H "Authorization: Bearer ${BITBUCKET_TOKEN}" "https://api.bitbucket.org/2.0/..."

ALWAYS use the provided helper functions:

# ✅ CORRECT - Use helper functions
bitbucket_test                              # Test connection
bitbucket_user                              # Get current user
bitbucket_pr myworkspace myrepo 123         # Get PR details

The helper functions handle authentication, error handling, retries, and output formatting automatically.

CRITICAL: Workspace and Repo Slug Parameters

ALL commands require explicit workspace and repo_slug as parameters.

bitbucket_pr myworkspace myrepo 123        # Get PR details
bitbucket_pr_diff myworkspace myrepo 123   # Get PR diff

Code Review Helper Functions (Bitbucket)

Inline comment with suggestion block:

bitbucket_create_pr_comment myworkspace myrepo 123 "file.py" 45 'Comment text

```suggestion
fixed code
```
'

• Use single quotes to preserve backticks literally - NO escaping needed

Discussion comment (not line-specific):

bitbucket_create_pr_discussion myworkspace myrepo 123 'Overall review summary'

Suggestion Block Syntax (CRITICAL)

✅ CORRECT - Single quotes preserve backticks:

bitbucket_create_pr_comment myworkspace myrepo 123 "src/app.py" 45 '🔴 CRITICAL: Issue

```suggestion
if not input:
    raise ValueError("Required")
```
'

❌ WRONG - Escaped backticks break rendering:

bitbucket_create_pr_comment myworkspace myrepo 123 "src/app.py" 45 "\`\`\`suggestion
code
\`\`\`"

Key rules:

• Use single quotes to wrap comment body containing markdown
• Backticks inside single quotes are literal - write them normally
• NEVER escape backticks with backslashes (\`) - this breaks Bitbucket's markdown parser
• Triple backticks for suggestion blocks must be literal: ```suggestion

Essential Read Commands

Connection and user info:

bitbucket_test                              # Test connection
bitbucket_user                              # Get current user info
bitbucket_workspaces                        # List accessible workspaces

Repository info:

bitbucket_repo myworkspace myrepo           # Get repository details
bitbucket_repos myworkspace                 # List repositories in workspace
bitbucket_branches myworkspace myrepo       # List branches

Pull request info:

bitbucket_pr myworkspace myrepo 123                # Get PR details
bitbucket_pr_diff myworkspace myrepo 123           # Get PR diff
bitbucket_pr_comments myworkspace myrepo 123       # Get PR comments

Pipeline info:

bitbucket_pipeline myworkspace myrepo PIPELINE_UUID           # Get pipeline details
bitbucket_pipeline_steps myworkspace myrepo PIPELINE_UUID     # Get pipeline steps

Supported Parameters Reference

bitbucket_pr - Get pull request details

Required parameters:

1. workspace : Workspace slug
2. repo_slug : Repository slug
3. pr_id : Pull request ID

Example:

bitbucket_pr myworkspace myrepo 123

bitbucket_pr_diff - Get pull request diff

Required parameters:

1. workspace : Workspace slug
2. repo_slug : Repository slug
3. pr_id : Pull request ID

Returns: Unified diff text

bitbucket_pr_comments - Get PR comments

Required parameters:

1. workspace : Workspace slug
2. repo_slug : Repository slug
3. pr_id : Pull request ID

Returns: JSON array of comment objects

bitbucket_repos - List repositories

Required parameters:

1. workspace : Workspace slug

Optional parameters:

• Second param: Results per page (default: 25)

Example:

bitbucket_repos myworkspace 50  # Get up to 50 repos

Write Commands (Code Review)

bitbucket_create_pr_comment - Inline code comment

Required parameters:

1. workspace : Workspace slug
2. repo_slug : Repository slug
3. pr_id : Pull request ID
4. file_path : Path to file (e.g., 'src/app.py')
5. line_number : Line number on NEW side of diff
6. body : Comment text (use single quotes for markdown)

Example with suggestion:

bitbucket_create_pr_comment myworkspace myrepo 123 "src/auth.py" 45 'Add input validation

```suggestion
if not validate_input(data):
    raise ValueError("Invalid input")
```
'

bitbucket_create_pr_discussion - General PR comment

Required parameters:

1. workspace : Workspace slug
2. repo_slug : Repository slug
3. pr_id : Pull request ID
4. body : Comment text

Use this for:

• Overall review summaries
• General feedback that doesn't apply to specific lines

Example:

bitbucket_create_pr_discussion myworkspace myrepo 123 'Code Review Summary

Looks good overall:
- 3 files reviewed
- 2 inline comments posted
- Ready for merge'

bitbucket_update_comment - Update existing comment

Required parameters:

1. workspace : Workspace slug
2. repo_slug : Repository slug
3. pr_id : Pull request ID
4. comment_id : Comment ID to update
5. body : New comment text

bitbucket_delete_comment - Delete comment

Required parameters:

1. workspace : Workspace slug
2. repo_slug : Repository slug
3. pr_id : Pull request ID
4. comment_id : Comment ID to delete

Key Rules

1. ALWAYS use helper functions for code review inline comments - Use bitbucket_create_pr_comment
2. Always specify workspace and repo_slug - Every command needs them
3. For general operations: Use helper functions (list, view, etc.)
4. Write operations: All require user approval
5. Suggestion blocks: Must use helper functions with single quotes
6. Multi-repo: Use explicit workspace/repo for each command:

   bitbucket_pr workspace1 frontend-repo 45
   bitbucket_pr workspace1 backend-repo 67
   

Errors

Critical Operations

⚠️ NEVER do these without explicit user instruction:

• bitbucket_delete_comment - Only on explicit request
• Any operation that modifies PR state - Only on explicit request

API Notes

• Bitbucket Cloud API 2.0 is used
• All responses are paginated (helper handles this)
• Rate limiting: 1000 requests/hour per user
• Token expiration: OAuth tokens expire, helper shows warning

Output Format

Present results as a structured report:

Bitbucket Report
════════════════
Resources discovered: [count]

Resource       Status    Key Metric    Issues
──────────────────────────────────────────────
[name]         [ok/warn] [value]       [findings]

Summary: [total] resources | [ok] healthy | [warn] warnings | [crit] critical
Action Items: [list of prioritized findings]

Target ≤50 lines of output. Use tables for multi-resource comparisons.

Anti-Hallucination Rules

1. NEVER assume resource names — always discover via CLI/API in Phase 1 before referencing in Phase 2.
2. NEVER fabricate metric names or dimensions — verify against the service documentation or --help output.
3. NEVER mix CLI commands between service versions — confirm which version/API you are targeting.
4. ALWAYS use the discovery → verify → analyze chain — every resource referenced must have been discovered first.
5. ALWAYS handle empty results gracefully — an empty response is valid data, not an error to retry.

Counter-Rationalizations