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.
Toolkit docs: composio.dev/toolkits/bitbucket
通过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 - 如果连接未处于ACTIVE状态,请按照返回的认证链接完成Bitbucket OAuth授权
- 在运行任何工作流之前,确认连接状态显示为ACTIVE
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 - - 创建新的拉取请求,需指定标题、源分支,可选择添加评审人【必需步骤】
BITBUCKET_CREATE_PULL_REQUEST - - 根据状态(OPEN、MERGED、DECLINED)筛选列出拉取请求【可选步骤】
BITBUCKET_LIST_PULL_REQUESTS - - 通过ID获取特定拉取请求的完整详情【可选步骤】
BITBUCKET_GET_PULL_REQUEST - - 获取统一差异对比用于代码评审【可选步骤】
BITBUCKET_GET_PULL_REQUEST_DIFF - - 获取变更文件及增删行数统计【可选步骤】
BITBUCKET_GET_PULL_REQUEST_DIFFSTAT
关键参数:
- : 工作区slug或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操作中是整数,但在拉取请求列表中返回的是字符串形式
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
关键参数:
- : 工作区slug(通过LIST_WORKSPACES获取)
workspace - : 用于创建/删除操作的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_BRANCHtarget_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
适用场景: 用户需要为拉取请求添加评审评论,包括代码行内评论
工具执行顺序:
- - 获取拉取请求详情并验证其存在【前提步骤】
BITBUCKET_GET_PULL_REQUEST - - 查看实际代码变更【前提步骤】
BITBUCKET_GET_PULL_REQUEST_DIFF - - 获取变更文件列表【可选步骤】
BITBUCKET_GET_PULL_REQUEST_DIFFSTAT - - 发布评审评论【必需步骤】
BITBUCKET_CREATE_PULL_REQUEST_COMMENT
关键参数:
- : 拉取请求的字符串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:
- 工作区: 使用获取工作区slug
BITBUCKET_LIST_WORKSPACES - 仓库: 使用并结合
BITBUCKET_LIST_REPOSITORIES_IN_WORKSPACE筛选器找到仓库slugq - 分支: 使用验证分支是否存在,再创建拉取请求
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条;请显式设置(拉取请求最多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查询语言可用于列表端点:
- 字符串值必须使用双引号:
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)
- 工作区: slug字符串(例如)或带大括号的UUID(
my-workspace){uuid} - 评审人UUID必须包含大括号:
{123e4567-e89b-12d3-a456-426614174000} - 问题ID是字符串;拉取请求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中不是有效字段——请使用
repositoryname
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
| 任务 | 工具标识 | 关键参数 |
|---|---|---|
| 列出工作区 | | |
| 列出仓库 | | |
| 创建仓库 | | |
| 删除仓库 | | |
| 列出分支 | | |
| 创建分支 | | |
| 列出拉取请求 | | |
| 创建拉取请求 | | |
| 获取拉取请求详情 | | |
| 获取拉取请求差异对比 | | |
| 获取拉取请求差异统计 | | |
| 为拉取请求添加评论 | | |
| 列出问题 | | |
| 创建问题 | | |
| 更新问题 | | |
| 为问题添加评论 | | |
| 删除问题 | | |
| 列出成员 | | |
由 Composio 提供支持
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 | | |
Powered by Composio
—