Bitbucket Automation

1---
2name: bitbucket-automation
3description: "Automate Bitbucket repositories, pull requests, branches, issues, and workspace management via Rube MCP (Composio). Always search tools first for current schemas."
4requires:
5  mcp: [rube]
6---
7 
8# Bitbucket Automation via Rube MCP
9 
10Automate Bitbucket operations including repository management, pull request workflows, branch operations, issue tracking, and workspace administration through Composio's Bitbucket toolkit.
11 
12## Prerequisites
13 
14- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
15- Active Bitbucket connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `bitbucket`
16- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
17 
18## Setup
19 
20**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
21 
22 
231. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
242. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `bitbucket`
253. If connection is not ACTIVE, follow the returned auth link to complete Bitbucket OAuth
264. Confirm connection status shows ACTIVE before running any workflows
27 
28## Core Workflows
29 
30### 1. Manage Pull Requests
31 
32**When to use**: User wants to create, review, or inspect pull requests
33 
34**Tool sequence**:
351. `BITBUCKET_LIST_WORKSPACES` - Discover accessible workspaces [Prerequisite]
362. `BITBUCKET_LIST_REPOSITORIES_IN_WORKSPACE` - Find the target repository [Prerequisite]
373. `BITBUCKET_LIST_BRANCHES` - Verify source and destination branches exist [Prerequisite]
384. `BITBUCKET_CREATE_PULL_REQUEST` - Create a new PR with title, source branch, and optional reviewers [Required]
395. `BITBUCKET_LIST_PULL_REQUESTS` - List PRs filtered by state (OPEN, MERGED, DECLINED) [Optional]
406. `BITBUCKET_GET_PULL_REQUEST` - Get full details of a specific PR by ID [Optional]
417. `BITBUCKET_GET_PULL_REQUEST_DIFF` - Fetch unified diff for code review [Optional]
428. `BITBUCKET_GET_PULL_REQUEST_DIFFSTAT` - Get changed files with lines added/removed [Optional]
43 
44**Key parameters**:
45- `workspace`: Workspace slug or UUID (required for all operations)
46- `repo_slug`: URL-friendly repository name
47- `source_branch`: Branch with changes to merge
48- `destination_branch`: Target branch (defaults to repo main branch if omitted)
49- `reviewers`: List of objects with `uuid` field for reviewer assignment
50- `state`: Filter for LIST_PULL_REQUESTS - `OPEN`, `MERGED`, or `DECLINED`
51- `max_chars`: Truncation limit for GET_PULL_REQUEST_DIFF to handle large diffs
52 
53**Pitfalls**:
54- `reviewers` expects an array of objects with `uuid` key, NOT usernames: `[{"uuid": "{...}"}]`
55- UUID format must include curly braces: `{123e4567-e89b-12d3-a456-426614174000}`
56- `destination_branch` defaults to the repo's main branch if omitted, which may not be `main`
57- `pull_request_id` is an integer for GET/DIFF operations but comes back as part of PR listing
58- Large diffs can overwhelm context; always set `max_chars` (e.g., 50000) on GET_PULL_REQUEST_DIFF
59 
60### 2. Manage Repositories and Workspaces
61 
62**When to use**: User wants to list, create, or delete repositories or explore workspaces
63 
64**Tool sequence**:
651. `BITBUCKET_LIST_WORKSPACES` - List all accessible workspaces [Required]
662. `BITBUCKET_LIST_REPOSITORIES_IN_WORKSPACE` - List repos with optional BBQL filtering [Required]
673. `BITBUCKET_CREATE_REPOSITORY` - Create a new repo with language, privacy, and project settings [Optional]
684. `BITBUCKET_DELETE_REPOSITORY` - Permanently delete a repository (irreversible) [Optional]
695. `BITBUCKET_LIST_WORKSPACE_MEMBERS` - List members for reviewer assignment or access checks [Optional]
70 
71**Key parameters**:
72- `workspace`: Workspace slug (find via LIST_WORKSPACES)
73- `repo_slug`: URL-friendly name for create/delete
74- `q`: BBQL query filter (e.g., `name~"api"`, `project.key="PROJ"`, `is_private=true`)
75- `role`: Filter repos by user role: `member`, `contributor`, `admin`, `owner`
76- `sort`: Sort field with optional `-` prefix for descending (e.g., `-updated_on`)
77- `is_private`: Boolean for repository visibility (defaults to `true`)
78- `project_key`: Bitbucket project key; omit to use workspace's oldest project
79 
80**Pitfalls**:
81- `BITBUCKET_DELETE_REPOSITORY` is **irreversible** and does not affect forks
82- BBQL string values MUST be enclosed in double quotes: `name~"my-repo"` not `name~my-repo`
83- `repository` is NOT a valid BBQL field; use `name` instead
84- Default pagination is 10 results; set `pagelen` explicitly for complete listings
85- `CREATE_REPOSITORY` defaults to private; set `is_private: false` for public repos
86 
87### 3. Manage Issues
88 
89**When to use**: User wants to create, update, list, or comment on repository issues
90 
91**Tool sequence**:
921. `BITBUCKET_LIST_ISSUES` - List issues with optional filters for state, priority, kind, assignee [Required]
932. `BITBUCKET_CREATE_ISSUE` - Create a new issue with title, content, priority, and kind [Required]
943. `BITBUCKET_UPDATE_ISSUE` - Modify issue attributes (state, priority, assignee, etc.) [Optional]
954. `BITBUCKET_CREATE_ISSUE_COMMENT` - Add a markdown comment to an existing issue [Optional]
965. `BITBUCKET_DELETE_ISSUE` - Permanently delete an issue [Optional]
97 
98**Key parameters**:
99- `issue_id`: String identifier for the issue
100- `title`, `content`: Required for creation
101- `kind`: `bug`, `enhancement`, `proposal`, or `task`
102- `priority`: `trivial`, `minor`, `major`, `critical`, or `blocker`
103- `state`: `new`, `open`, `resolved`, `on hold`, `invalid`, `duplicate`, `wontfix`, `closed`
104- `assignee`: Bitbucket username for CREATE; `assignee_account_id` (UUID) for UPDATE
105- `due_on`: ISO 8601 format date string
106 
107**Pitfalls**:
108- Issue tracker must be enabled on the repository (`has_issues: true`) or API calls will fail
109- `CREATE_ISSUE` uses `assignee` (username string), but `UPDATE_ISSUE` uses `assignee_account_id` (UUID) -- they are different fields
110- `DELETE_ISSUE` is permanent with no undo
111- `state` values include spaces: `"on hold"` not `"on_hold"`
112- Filtering by `assignee` in LIST_ISSUES uses account ID, not username; use `"null"` string for unassigned
113 
114### 4. Manage Branches
115 
116**When to use**: User wants to create branches or explore branch structure
117 
118**Tool sequence**:
1191. `BITBUCKET_LIST_BRANCHES` - List branches with optional BBQL filter and sorting [Required]
1202. `BITBUCKET_CREATE_BRANCH` - Create a new branch from a specific commit hash [Required]
121 
122**Key parameters**:
123- `name`: Branch name without `refs/heads/` prefix (e.g., `feature/new-login`)
124- `target_hash`: Full SHA1 commit hash to branch from (must exist in repo)
125- `q`: BBQL filter (e.g., `name~"feature/"`, `name="main"`)
126- `sort`: Sort by `name` or `-target.date` (descending commit date)
127- `pagelen`: 1-100 results per page (default is 10)
128 
129**Pitfalls**:
130- `CREATE_BRANCH` requires a full commit hash, NOT a branch name as `target_hash`
131- Do NOT include `refs/heads/` prefix in branch names
132- Branch names must follow Bitbucket naming conventions (alphanumeric, `/`, `.`, `_`, `-`)
133- BBQL string values need double quotes: `name~"feature/"` not `name~feature/`
134 
135### 5. Review Pull Requests with Comments
136 
137**When to use**: User wants to add review comments to pull requests, including inline code comments
138 
139**Tool sequence**:
1401. `BITBUCKET_GET_PULL_REQUEST` - Get PR details and verify it exists [Prerequisite]
1412. `BITBUCKET_GET_PULL_REQUEST_DIFF` - Review the actual code changes [Prerequisite]
1423. `BITBUCKET_GET_PULL_REQUEST_DIFFSTAT` - Get list of changed files [Optional]
1434. `BITBUCKET_CREATE_PULL_REQUEST_COMMENT` - Post review comments [Required]
144 
145**Key parameters**:
146- `pull_request_id`: String ID of the PR
147- `content_raw`: Markdown-formatted comment text
148- `content_markup`: Defaults to `markdown`; also supports `plaintext`
149- `inline`: Object with `path`, `from`, `to` for inline code comments
150- `parent_comment_id`: Integer ID for threaded replies to existing comments
151 
152**Pitfalls**:
153- `pull_request_id` is a string in CREATE_PULL_REQUEST_COMMENT but an integer in GET_PULL_REQUEST
154- Inline comments require `inline.path` at minimum; `from`/`to` are optional line numbers
155- `parent_comment_id` creates a threaded reply; omit for top-level comments
156- Line numbers in inline comments reference the diff, not the source file
157 
158## Common Patterns
159 
160### ID Resolution
161Always resolve human-readable names to IDs before operations:
162- **Workspace**: `BITBUCKET_LIST_WORKSPACES` to get workspace slugs
163- **Repository**: `BITBUCKET_LIST_REPOSITORIES_IN_WORKSPACE` with `q` filter to find repo slugs
164- **Branch**: `BITBUCKET_LIST_BRANCHES` to verify branch existence before PR creation
165- **Members**: `BITBUCKET_LIST_WORKSPACE_MEMBERS` to get UUIDs for reviewer assignment
166 
167### Pagination
168Bitbucket uses page-based pagination (not cursor-based):
169- Use `page` (starts at 1) and `pagelen` (items per page) parameters
170- Default page size is typically 10; set `pagelen` explicitly (max 50 for PRs, 100 for others)
171- Check response for `next` URL or total count to determine if more pages exist
172- Always iterate through all pages for complete results
173 
174### BBQL Filtering
175Bitbucket Query Language is available on list endpoints:
176- String values MUST use double quotes: `name~"pattern"`
177- Operators: `=` (exact), `~` (contains), `!=` (not equal), `>`, `>=`, `<`, `<=`
178- Combine with `AND` / `OR`: `name~"api" AND is_private=true`
179 
180## Known Pitfalls
181 
182### ID Formats
183- Workspace: slug string (e.g., `my-workspace`) or UUID in braces (`{uuid}`)
184- Reviewer UUIDs must include curly braces: `{123e4567-e89b-12d3-a456-426614174000}`
185- Issue IDs are strings; PR IDs are integers in some tools, strings in others
186- Commit hashes must be full SHA1 (40 characters)
187 
188### Parameter Quirks
189- `assignee` vs `assignee_account_id`: CREATE_ISSUE uses username, UPDATE_ISSUE uses UUID
190- `state` values for issues include spaces: `"on hold"`, not `"on_hold"`
191- `destination_branch` omission defaults to repo main branch, not `main` literally
192- BBQL `repository` is not a valid field -- use `name`
193 
194### Rate Limits
195- Bitbucket Cloud API has rate limits; large batch operations should include delays
196- Paginated requests count against rate limits; minimize unnecessary page fetches
197 
198### Destructive Operations
199- `BITBUCKET_DELETE_REPOSITORY` is irreversible and does not remove forks
200- `BITBUCKET_DELETE_ISSUE` is permanent with no recovery option
201- Always confirm with the user before executing delete operations
202 
203## Quick Reference
204 
205| Task | Tool Slug | Key Params |
206|------|-----------|------------|
207| List workspaces | `BITBUCKET_LIST_WORKSPACES` | `q`, `sort` |
208| List repos | `BITBUCKET_LIST_REPOSITORIES_IN_WORKSPACE` | `workspace`, `q`, `role` |
209| Create repo | `BITBUCKET_CREATE_REPOSITORY` | `workspace`, `repo_slug`, `is_private` |
210| Delete repo | `BITBUCKET_DELETE_REPOSITORY` | `workspace`, `repo_slug` |
211| List branches | `BITBUCKET_LIST_BRANCHES` | `workspace`, `repo_slug`, `q` |
212| Create branch | `BITBUCKET_CREATE_BRANCH` | `workspace`, `repo_slug`, `name`, `target_hash` |
213| List PRs | `BITBUCKET_LIST_PULL_REQUESTS` | `workspace`, `repo_slug`, `state` |
214| Create PR | `BITBUCKET_CREATE_PULL_REQUEST` | `workspace`, `repo_slug`, `title`, `source_branch` |
215| Get PR details | `BITBUCKET_GET_PULL_REQUEST` | `workspace`, `repo_slug`, `pull_request_id` |
216| Get PR diff | `BITBUCKET_GET_PULL_REQUEST_DIFF` | `workspace`, `repo_slug`, `pull_request_id`, `max_chars` |
217| Get PR diffstat | `BITBUCKET_GET_PULL_REQUEST_DIFFSTAT` | `workspace`, `repo_slug`, `pull_request_id` |
218| Comment on PR | `BITBUCKET_CREATE_PULL_REQUEST_COMMENT` | `workspace`, `repo_slug`, `pull_request_id`, `content_raw` |
219| List issues | `BITBUCKET_LIST_ISSUES` | `workspace`, `repo_slug`, `state`, `priority` |
220| Create issue | `BITBUCKET_CREATE_ISSUE` | `workspace`, `repo_slug`, `title`, `content` |
221| Update issue | `BITBUCKET_UPDATE_ISSUE` | `workspace`, `repo_slug`, `issue_id` |
222| Comment on issue | `BITBUCKET_CREATE_ISSUE_COMMENT` | `workspace`, `repo_slug`, `issue_id`, `content` |
223| Delete issue | `BITBUCKET_DELETE_ISSUE` | `workspace`, `repo_slug`, `issue_id` |
224| List members | `BITBUCKET_LIST_WORKSPACE_MEMBERS` | `workspace` |
225