bitbucket-automation
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseBitbucket Automation via Rube MCP
基于Rube MCP的Bitbucket自动化
Automate Bitbucket operations including repository management, pull request workflows, branch operations, issue tracking, and workspace administration through Composio's Bitbucket toolkit.
通过Composio的Bitbucket工具包,实现Bitbucket操作的自动化,包括仓库管理、拉取请求工作流、分支操作、问题追踪以及工作区管理。
Prerequisites
前提条件
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
- Active Bitbucket connection via with toolkit
RUBE_MANAGE_CONNECTIONSbitbucket - Always call first to get current tool schemas
RUBE_SEARCH_TOOLS
- 必须已连接Rube MCP(需提供RUBE_SEARCH_TOOLS)
- 通过并使用
RUBE_MANAGE_CONNECTIONS工具包,建立有效的Bitbucket连接bitbucket - 请始终先调用以获取最新的工具架构
RUBE_SEARCH_TOOLS
Setup
设置步骤
Get Rube MCP: Add as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
https://rube.app/mcp- Verify Rube MCP is available by confirming responds
RUBE_SEARCH_TOOLS - Call with toolkit
RUBE_MANAGE_CONNECTIONSbitbucket - If connection is not ACTIVE, follow the returned auth link to complete Bitbucket OAuth
- Confirm connection status shows ACTIVE before running any workflows
获取Rube MCP:在客户端配置中添加作为MCP服务器。无需API密钥 —— 只需添加该端点即可使用。
https://rube.app/mcp- 确认可正常响应,以此验证Rube MCP是否可用
RUBE_SEARCH_TOOLS - 调用并指定工具包为
RUBE_MANAGE_CONNECTIONSbitbucket - 如果连接状态未激活,请按照返回的授权链接完成Bitbucket OAuth认证
- 在运行任何工作流之前,确认连接状态显示为已激活
Core Workflows
核心工作流
1. Manage Pull Requests
1. 管理拉取请求
When to use: User wants to create, review, or inspect pull requests
Tool sequence:
- - Discover accessible workspaces [Prerequisite]
BITBUCKET_LIST_WORKSPACES - - Find the target repository [Prerequisite]
BITBUCKET_LIST_REPOSITORIES_IN_WORKSPACE - - Verify source and destination branches exist [Prerequisite]
BITBUCKET_LIST_BRANCHES - - Create a new PR with title, source branch, and optional reviewers [Required]
BITBUCKET_CREATE_PULL_REQUEST - - List PRs filtered by state (OPEN, MERGED, DECLINED) [Optional]
BITBUCKET_LIST_PULL_REQUESTS - - Get full details of a specific PR by ID [Optional]
BITBUCKET_GET_PULL_REQUEST - - Fetch unified diff for code review [Optional]
BITBUCKET_GET_PULL_REQUEST_DIFF - - Get changed files with lines added/removed [Optional]
BITBUCKET_GET_PULL_REQUEST_DIFFSTAT
Key parameters:
- : Workspace slug or UUID (required for all operations)
workspace - : URL-friendly repository name
repo_slug - : Branch with changes to merge
source_branch - : Target branch (defaults to repo main branch if omitted)
destination_branch - : List of objects with
reviewersfield for reviewer assignmentuuid - : Filter for LIST_PULL_REQUESTS -
state,OPEN, orMERGEDDECLINED - : Truncation limit for GET_PULL_REQUEST_DIFF to handle large diffs
max_chars
Pitfalls:
- expects an array of objects with
reviewerskey, NOT usernames:uuid[{"uuid": "{...}"}] - UUID format must include curly braces:
{123e4567-e89b-12d3-a456-426614174000} - defaults to the repo's main branch if omitted, which may not be
destination_branchmain - is an integer for GET/DIFF operations but comes back as part of PR listing
pull_request_id - Large diffs can overwhelm context; always set (e.g., 50000) on GET_PULL_REQUEST_DIFF
max_chars
适用场景:用户需要创建、评审或查看拉取请求
工具执行序列:
- - 查看可访问的工作区 [前置条件]
BITBUCKET_LIST_WORKSPACES - - 找到目标仓库 [前置条件]
BITBUCKET_LIST_REPOSITORIES_IN_WORKSPACE - - 验证源分支和目标分支是否存在 [前置条件]
BITBUCKET_LIST_BRANCHES - - 创建新的PR,需指定标题、源分支,可选择添加评审人 [必填步骤]
BITBUCKET_CREATE_PULL_REQUEST - - 按状态(OPEN、MERGED、DECLINED)筛选列出PR [可选步骤]
BITBUCKET_LIST_PULL_REQUESTS - - 通过ID获取特定PR的完整详情 [可选步骤]
BITBUCKET_GET_PULL_REQUEST - - 获取统一差异对比用于代码评审 [可选步骤]
BITBUCKET_GET_PULL_REQUEST_DIFF - - 获取变更文件及增删行数统计 [可选步骤]
BITBUCKET_GET_PULL_REQUEST_DIFFSTAT
关键参数:
- : 工作区别名或UUID(所有操作必填)
workspace - : 符合URL规范的仓库名称
repo_slug - : 包含待合并变更的分支
source_branch - : 目标分支(若省略则默认使用仓库的主分支)
destination_branch - : 包含
reviewers字段的对象列表,用于指定评审人uuid - : 用于
state的筛选条件 -LIST_PULL_REQUESTS、OPEN或MERGEDDECLINED - :
max_chars的截断限制,用于处理大型差异对比内容GET_PULL_REQUEST_DIFF
注意事项:
- 参数要求传入包含
reviewers键的对象数组,而非用户名:uuid[{"uuid": "{...}"}] - UUID格式必须包含大括号:
{123e4567-e89b-12d3-a456-426614174000} - 若省略,默认使用仓库的主分支,但该分支名称可能不是
destination_branchmain - 在GET/DIFF操作中为整数,但会作为PR列表的返回字段
pull_request_id - 大型差异对比内容可能超出上下文限制;请始终为设置
GET_PULL_REQUEST_DIFF(例如50000)max_chars
2. Manage Repositories and Workspaces
2. 管理仓库与工作区
When to use: User wants to list, create, or delete repositories or explore workspaces
Tool sequence:
- - List all accessible workspaces [Required]
BITBUCKET_LIST_WORKSPACES - - List repos with optional BBQL filtering [Required]
BITBUCKET_LIST_REPOSITORIES_IN_WORKSPACE - - Create a new repo with language, privacy, and project settings [Optional]
BITBUCKET_CREATE_REPOSITORY - - Permanently delete a repository (irreversible) [Optional]
BITBUCKET_DELETE_REPOSITORY - - List members for reviewer assignment or access checks [Optional]
BITBUCKET_LIST_WORKSPACE_MEMBERS
Key parameters:
- : Workspace slug (find via LIST_WORKSPACES)
workspace - : URL-friendly name for create/delete
repo_slug - : BBQL query filter (e.g.,
q,name~"api",project.key="PROJ")is_private=true - : Filter repos by user role:
role,member,contributor,adminowner - : Sort field with optional
sortprefix for descending (e.g.,-)-updated_on - : Boolean for repository visibility (defaults to
is_private)true - : Bitbucket project key; omit to use workspace's oldest project
project_key
Pitfalls:
- is irreversible and does not affect forks
BITBUCKET_DELETE_REPOSITORY - BBQL string values MUST be enclosed in double quotes: not
name~"my-repo"name~my-repo - is NOT a valid BBQL field; use
repositoryinsteadname - Default pagination is 10 results; set explicitly for complete listings
pagelen - defaults to private; set
CREATE_REPOSITORYfor public reposis_private: false
适用场景:用户需要列出、创建或删除仓库,或查看工作区信息
工具执行序列:
- - 列出所有可访问的工作区 [必填步骤]
BITBUCKET_LIST_WORKSPACES - - 列出仓库,可通过BBQL筛选 [必填步骤]
BITBUCKET_LIST_REPOSITORIES_IN_WORKSPACE - - 创建新仓库,可设置语言、隐私性及项目配置 [可选步骤]
BITBUCKET_CREATE_REPOSITORY - - 永久删除仓库(不可恢复) [可选步骤]
BITBUCKET_DELETE_REPOSITORY - - 列出工作区成员,用于指定评审人或权限检查 [可选步骤]
BITBUCKET_LIST_WORKSPACE_MEMBERS
关键参数:
- : 工作区别名(可通过
workspace获取)LIST_WORKSPACES - : 用于创建/删除操作的符合URL规范的仓库名称
repo_slug - : BBQL查询筛选条件(例如
q,name~"api",project.key="PROJ")is_private=true - : 按用户角色筛选仓库:
role、member、contributor、adminowner - : 排序字段,可添加
sort前缀表示降序(例如-)-updated_on - : 仓库可见性的布尔值(默认值为
is_private)true - : Bitbucket项目密钥;若省略则使用工作区中创建时间最早的项目
project_key
注意事项:
- 操作不可恢复,且不会影响派生仓库
BITBUCKET_DELETE_REPOSITORY - BBQL的字符串值必须用双引号包裹:而非
name~"my-repo"name~my-repo - 不是有效的BBQL字段;请使用
repository替代name - 默认分页为10条结果;如需完整列表请显式设置参数
pagelen - 默认创建私有仓库;若需创建公开仓库请设置
CREATE_REPOSITORYis_private: false
3. Manage Issues
3. 管理问题
When to use: User wants to create, update, list, or comment on repository issues
Tool sequence:
- - List issues with optional filters for state, priority, kind, assignee [Required]
BITBUCKET_LIST_ISSUES - - Create a new issue with title, content, priority, and kind [Required]
BITBUCKET_CREATE_ISSUE - - Modify issue attributes (state, priority, assignee, etc.) [Optional]
BITBUCKET_UPDATE_ISSUE - - Add a markdown comment to an existing issue [Optional]
BITBUCKET_CREATE_ISSUE_COMMENT - - Permanently delete an issue [Optional]
BITBUCKET_DELETE_ISSUE
Key parameters:
- : String identifier for the issue
issue_id - ,
title: Required for creationcontent - :
kind,bug,enhancement, orproposaltask - :
priority,trivial,minor,major, orcriticalblocker - :
state,new,open,resolved,on hold,invalid,duplicate,wontfixclosed - : Bitbucket username for CREATE;
assignee(UUID) for UPDATEassignee_account_id - : ISO 8601 format date string
due_on
Pitfalls:
- Issue tracker must be enabled on the repository () or API calls will fail
has_issues: true - uses
CREATE_ISSUE(username string), butassigneeusesUPDATE_ISSUE(UUID) -- they are different fieldsassignee_account_id - is permanent with no undo
DELETE_ISSUE - values include spaces:
statenot"on hold""on_hold" - Filtering by in LIST_ISSUES uses account ID, not username; use
assigneestring for unassigned"null"
适用场景:用户需要创建、更新、列出或评论仓库问题
工具执行序列:
- - 列出问题,可按状态、优先级、类型、经办人筛选 [必填步骤]
BITBUCKET_LIST_ISSUES - - 创建新问题,需指定标题、内容、优先级及类型 [必填步骤]
BITBUCKET_CREATE_ISSUE - - 修改问题属性(状态、优先级、经办人等) [可选步骤]
BITBUCKET_UPDATE_ISSUE - - 为现有问题添加Markdown格式的评论 [可选步骤]
BITBUCKET_CREATE_ISSUE_COMMENT - - 永久删除问题 [可选步骤]
BITBUCKET_DELETE_ISSUE
关键参数:
- : 问题的字符串标识符
issue_id - ,
title: 创建问题时必填content - : 问题类型:
kind、bug、enhancement或proposaltask - : 问题优先级:
priority、trivial、minor、major或criticalblocker - : 问题状态:
state、new、open、resolved、on hold、invalid、duplicate、wontfixclosed - : 创建问题时使用的Bitbucket用户名;更新问题时使用
assignee(UUID)assignee_account_id - : ISO 8601格式的日期字符串
due_on
注意事项:
- 仓库必须已启用问题追踪功能(),否则API调用会失败
has_issues: true - 使用
CREATE_ISSUE(字符串类型的用户名),但assignee使用UPDATE_ISSUE(UUID)—— 这是两个不同的参数assignee_account_id - 操作永久生效,无法撤销
DELETE_ISSUE - 参数的部分值包含空格:
state而非"on hold""on_hold" - 在中按
LIST_ISSUES筛选时需使用账户ID而非用户名;若要筛选未分配的问题,请使用字符串assignee"null"
4. Manage Branches
4. 管理分支
When to use: User wants to create branches or explore branch structure
Tool sequence:
- - List branches with optional BBQL filter and sorting [Required]
BITBUCKET_LIST_BRANCHES - - Create a new branch from a specific commit hash [Required]
BITBUCKET_CREATE_BRANCH
Key parameters:
- : Branch name without
nameprefix (e.g.,refs/heads/)feature/new-login - : Full SHA1 commit hash to branch from (must exist in repo)
target_hash - : BBQL filter (e.g.,
q,name~"feature/")name="main" - : Sort by
sortorname(descending commit date)-target.date - : 1-100 results per page (default is 10)
pagelen
Pitfalls:
- requires a full commit hash, NOT a branch name as
CREATE_BRANCHtarget_hash - Do NOT include prefix in branch names
refs/heads/ - Branch names must follow Bitbucket naming conventions (alphanumeric, ,
/,.,_)- - BBQL string values need double quotes: not
name~"feature/"name~feature/
适用场景:用户需要创建分支或查看分支结构
工具执行序列:
- - 列出分支,可通过BBQL筛选和排序 [必填步骤]
BITBUCKET_LIST_BRANCHES - - 基于特定提交哈希创建新分支 [必填步骤]
BITBUCKET_CREATE_BRANCH
关键参数:
- : 分支名称,无需添加
name前缀(例如refs/heads/)feature/new-login - : 用于创建分支的完整SHA1提交哈希(必须存在于仓库中)
target_hash - : BBQL筛选条件(例如
q,name~"feature/")name="main" - : 排序方式,可按
sort或name(提交日期降序)-target.date - : 每页显示1-100条结果(默认值为10)
pagelen
注意事项:
- 需要完整的提交哈希作为
CREATE_BRANCH,而非分支名称target_hash - 分支名称中请勿包含前缀
refs/heads/ - 分支名称必须符合Bitbucket的命名规范(允许字母数字、、
/、.、_)- - BBQL的字符串值需要用双引号包裹:而非
name~"feature/"name~feature/
5. Review Pull Requests with Comments
5. 为拉取请求添加评审评论
When to use: User wants to add review comments to pull requests, including inline code comments
Tool sequence:
- - Get PR details and verify it exists [Prerequisite]
BITBUCKET_GET_PULL_REQUEST - - Review the actual code changes [Prerequisite]
BITBUCKET_GET_PULL_REQUEST_DIFF - - Get list of changed files [Optional]
BITBUCKET_GET_PULL_REQUEST_DIFFSTAT - - Post review comments [Required]
BITBUCKET_CREATE_PULL_REQUEST_COMMENT
Key parameters:
- : String ID of the PR
pull_request_id - : Markdown-formatted comment text
content_raw - : Defaults to
content_markup; also supportsmarkdownplaintext - : Object with
inline,path,fromfor inline code commentsto - : Integer ID for threaded replies to existing comments
parent_comment_id
Pitfalls:
- is a string in CREATE_PULL_REQUEST_COMMENT but an integer in GET_PULL_REQUEST
pull_request_id - Inline comments require at minimum;
inline.path/fromare optional line numbersto - creates a threaded reply; omit for top-level comments
parent_comment_id - Line numbers in inline comments reference the diff, not the source file
适用场景:用户需要为拉取请求添加评审评论,包括代码行内评论
工具执行序列:
- - 获取PR详情并验证其存在 [前置条件]
BITBUCKET_GET_PULL_REQUEST - - 查看实际代码变更 [前置条件]
BITBUCKET_GET_PULL_REQUEST_DIFF - - 获取变更文件列表 [可选步骤]
BITBUCKET_GET_PULL_REQUEST_DIFFSTAT - - 发布评审评论 [必填步骤]
BITBUCKET_CREATE_PULL_REQUEST_COMMENT
关键参数:
- : PR的字符串ID
pull_request_id - : Markdown格式的评论内容
content_raw - : 默认值为
content_markup;也支持markdownplaintext - : 用于行内代码评论的对象,包含
inline、path、from字段to - : 用于回复现有评论的整数ID,可创建线程化回复
parent_comment_id
注意事项:
- 在中
CREATE_PULL_REQUEST_COMMENT是字符串,但在pull_request_id中是整数GET_PULL_REQUEST - 行内评论至少需要参数;
inline.path/from为可选行号to - 用于创建线程化回复;若省略则创建顶级评论
parent_comment_id - 行内评论中的行号引用的是差异对比内容中的行号,而非源文件中的行号
Common Patterns
通用模式
ID Resolution
ID解析
Always resolve human-readable names to IDs before operations:
- Workspace: to get workspace slugs
BITBUCKET_LIST_WORKSPACES - Repository: with
BITBUCKET_LIST_REPOSITORIES_IN_WORKSPACEfilter to find repo slugsq - Branch: to verify branch existence before PR creation
BITBUCKET_LIST_BRANCHES - Members: to get UUIDs for reviewer assignment
BITBUCKET_LIST_WORKSPACE_MEMBERS
在执行操作前,请始终将人类可读名称解析为对应的ID:
- 工作区: 通过获取工作区别名
BITBUCKET_LIST_WORKSPACES - 仓库: 通过并结合
BITBUCKET_LIST_REPOSITORIES_IN_WORKSPACE筛选条件找到仓库别名q - 分支: 在创建PR前,通过验证分支是否存在
BITBUCKET_LIST_BRANCHES - 成员: 通过获取用于指定评审人的UUID
BITBUCKET_LIST_WORKSPACE_MEMBERS
Pagination
分页
Bitbucket uses page-based pagination (not cursor-based):
- Use (starts at 1) and
page(items per page) parameterspagelen - Default page size is typically 10; set explicitly (max 50 for PRs, 100 for others)
pagelen - Check response for URL or total count to determine if more pages exist
next - Always iterate through all pages for complete results
Bitbucket使用基于页码的分页(而非游标分页):
- 使用(从1开始)和
page(每页结果数)参数pagelen - 默认每页大小通常为10条;请显式设置参数(PR的最大值为50,其他操作最大值为100)
pagelen - 检查响应中的链接或总结果数,以判断是否存在更多页面
next - 如需获取完整结果,请始终遍历所有页面
BBQL Filtering
BBQL筛选
Bitbucket Query Language is available on list endpoints:
- String values MUST use double quotes:
name~"pattern" - Operators: (exact),
=(contains),~(not equal),!=,>,>=,<<= - Combine with /
AND:ORname~"api" AND is_private=true
列表类接口支持Bitbucket查询语言(BBQL):
- 字符串值必须使用双引号:
name~"pattern" - 支持的运算符:(精确匹配)、
=(包含匹配)、~(不相等)、!=、>、>=、<<= - 可通过/
AND组合条件:ORname~"api" AND is_private=true
Known Pitfalls
已知注意事项
ID Formats
ID格式
- Workspace: slug string (e.g., ) or UUID in braces (
my-workspace){uuid} - Reviewer UUIDs must include curly braces:
{123e4567-e89b-12d3-a456-426614174000} - Issue IDs are strings; PR IDs are integers in some tools, strings in others
- Commit hashes must be full SHA1 (40 characters)
- 工作区:字符串别名(例如)或带大括号的UUID(
my-workspace){uuid} - 评审人UUID必须包含大括号:
{123e4567-e89b-12d3-a456-426614174000} - 问题ID为字符串;PR ID在部分工具中为整数,在其他工具中为字符串
- 提交哈希必须是完整的SHA1值(40个字符)
Parameter Quirks
参数特殊说明
- vs
assignee: CREATE_ISSUE uses username, UPDATE_ISSUE uses UUIDassignee_account_id - values for issues include spaces:
state, not"on hold""on_hold" - omission defaults to repo main branch, not
destination_branchliterallymain - BBQL is not a valid field -- use
repositoryname
- 与
assignee的区别:assignee_account_id使用用户名,CREATE_ISSUE使用UUIDUPDATE_ISSUE - 问题的参数部分值包含空格:
state,而非"on hold""on_hold" - 若省略,默认使用仓库的主分支,但该分支名称不一定是
destination_branchmain - BBQL中不是有效字段,请使用
repository替代name
Rate Limits
速率限制
- Bitbucket Cloud API has rate limits; large batch operations should include delays
- Paginated requests count against rate limits; minimize unnecessary page fetches
- Bitbucket Cloud API存在速率限制;大型批量操作应添加延迟
- 分页请求会占用速率限制配额;请尽量减少不必要的页面请求
Destructive Operations
破坏性操作
- is irreversible and does not remove forks
BITBUCKET_DELETE_REPOSITORY - is permanent with no recovery option
BITBUCKET_DELETE_ISSUE - Always confirm with the user before executing delete operations
- 操作不可恢复,且不会删除派生仓库
BITBUCKET_DELETE_REPOSITORY - 操作永久生效,无法恢复
BITBUCKET_DELETE_ISSUE - 在执行删除操作前,请始终与用户确认
Quick Reference
快速参考
| Task | Tool Slug | Key Params |
|---|---|---|
| List workspaces | | |
| List repos | | |
| Create repo | | |
| Delete repo | | |
| List branches | | |
| Create branch | | |
| List PRs | | |
| Create PR | | |
| Get PR details | | |
| Get PR diff | | |
| Get PR diffstat | | |
| Comment on PR | | |
| List issues | | |
| Create issue | | |
| Update issue | | |
| Comment on issue | | |
| Delete issue | | |
| List members | | |
| 任务 | 工具标识 | 关键参数 |
|---|---|---|
| 列出工作区 | | |
| 列出仓库 | | |
| 创建仓库 | | |
| 删除仓库 | | |
| 列出分支 | | |
| 创建分支 | | |
| 列出PR | | |
| 创建PR | | |
| 获取PR详情 | | |
| 获取PR差异对比 | | |
| 获取PR差异统计 | | |
| 评论PR | | |
| 列出问题 | | |
| 创建问题 | | |
| 更新问题 | | |
| 评论问题 | | |
| 删除问题 | | |
| 列出工作区成员 | | |