Bitbucket Cloud 集成

用于仓库管理、拉取请求、分支、提交和管道的 Bitbucket Cloud REST API v2 集成。

身份验证

Bitbucket Cloud 使用应用密码进行身份验证。所需的环境变量：

• - BITBUCKETWORKSPACE - 默认工作区标识符（例如 myteam）
• BITBUCKETUSERNAME - Bitbucket 用户名（非邮箱）
• BITBUCKETAPPPASSWORD - 来自 https://bitbucket.org/account/settings/app-passwords/ 的应用密码

创建具有所需权限的应用密码：

• - 仓库：读取、写入（用于仓库操作）
• 拉取请求：读取、写入（用于 PR 操作）
• 管道：读取（用于管道状态）
• 账户：读取（用于用户信息）

测试连接：
bash
curl -s -u $BITBUCKETUSERNAME:$BITBUCKETAPP_PASSWORD \
https://api.bitbucket.org/2.0/user | jq .

快速参考

所有操作均使用 scripts/bitbucket.py 脚本：

操作	命令
仓库
列出仓库

bitbucket.py repos |
| 查看仓库 | bitbucket.py repo my-repo |
| 创建仓库 | bitbucket.py create-repo my-new-repo --private |
| 拉取请求 | |
| 列出 PR | bitbucket.py prs my-repo |
| 查看 PR | bitbucket.py pr my-repo 42 |
| 创建 PR | bitbucket.py create-pr my-repo --title 功能 --source feature-branch |
| 评论 PR | bitbucket.py pr-comment my-repo 42 看起来不错！ |
| 批准 PR | bitbucket.py approve my-repo 42 |
| 合并 PR | bitbucket.py merge my-repo 42 |
| 拒绝 PR | bitbucket.py decline my-repo 42 |
| 分支 | |
| 列出分支 | bitbucket.py branches my-repo |
| 查看分支 | bitbucket.py branch my-repo main |
| 创建分支 | bitbucket.py create-branch my-repo feature-x --from main |
| 删除分支 | bitbucket.py delete-branch my-repo old-feature |
| 提交 | |
| 列出提交 | bitbucket.py commits my-repo |
| 查看提交 | bitbucket.py commit my-repo abc123 |
| 管道 | |
| 列出管道 | bitbucket.py pipelines my-repo |
| 查看管道 | bitbucket.py pipeline my-repo {uuid} |
| 管道步骤 | bitbucket.py pipeline-steps my-repo {uuid} |
| 工作区 | |
| 列出工作区 | bitbucket.py workspaces |
| 工作区成员 | bitbucket.py members |
| 当前用户 | bitbucket.py me |

常见工作流

仓库管理

bash

列出工作区中的所有仓库

bitbucket.py repos

分页列出

bitbucket.py repos --page 2 --pagelen 25

查看特定仓库详情

bitbucket.py repo my-repo

创建新的私有仓库

bitbucket.py create-repo my-new-repo --private --description 项目描述

创建具有特定项目的公共仓库

bitbucket.py create-repo my-public-repo --project PROJ

拉取请求工作流

bash

列出开放的拉取请求

bitbucket.py prs my-repo

列出所有 PR（包括已合并/已拒绝的）

bitbucket.py prs my-repo --state all

查看 PR 详情

bitbucket.py pr my-repo 42

创建拉取请求

bitbucket.py create-pr my-repo \ --title 添加新功能 \ --source feature-branch \ --destination main \ --description 此 PR 添加了...

添加评论

bitbucket.py pr-comment my-repo 42 看起来不错，只有一个问题...

批准 PR

bitbucket.py approve my-repo 42

取消批准（移除批准）

bitbucket.py unapprove my-repo 42

请求更改

bitbucket.py request-changes my-repo 42

使用默认策略合并

bitbucket.py merge my-repo 42

使用特定策略合并

bitbucket.py merge my-repo 42 --strategy squash

拒绝 PR

bitbucket.py decline my-repo 42

分支操作

bash

列出所有分支

bitbucket.py branches my-repo

查看分支详情

bitbucket.py branch my-repo feature-x

从 main 创建分支

bitbucket.py create-branch my-repo feature-y --from main

从特定提交创建分支

bitbucket.py create-branch my-repo hotfix-1 --from abc123def

删除分支（不能删除 main 分支）

bitbucket.py delete-branch my-repo old-feature

提交历史

bash

列出最近的提交（默认分支）

bitbucket.py commits my-repo

特定分支上的提交

bitbucket.py commits my-repo --branch feature-x

限制结果数量

bitbucket.py commits my-repo --pagelen 10

查看特定提交

bitbucket.py commit my-repo abc123def456

管道状态

bash

列出最近的管道

bitbucket.py pipelines my-repo

按状态筛选

bitbucket.py pipelines my-repo --status SUCCESSFUL bitbucket.py pipelines my-repo --status FAILED

查看管道详情

bitbucket.py pipeline my-repo {pipeline-uuid}

查看管道步骤

bitbucket.py pipeline-steps my-repo {pipeline-uuid}

触发管道

bitbucket.py run-pipeline my-repo --branch main

工作区和用户信息

bash

列出可访问的工作区

bitbucket.py workspaces

列出工作区成员

bitbucket.py members

获取当前用户信息

bitbucket.py me

合并策略

合并 PR 时，可用的策略有：

策略	描述
merge_commit	创建合并提交（默认）
squash

将所有提交压缩为一个 |
| fast_forward | 尽可能快进 |

管道状态

状态	描述
PENDING	等待开始
IN_PROGRESS

正在运行 | | SUCCESSFUL | 成功完成 | | FAILED | 完成但失败 | | STOPPED | 手动停止 |

错误处理

常见错误：

• - 401 未授权：检查 BITBUCKETUSERNAME 和 BITBUCKETAPP_PASSWORD
• 403 禁止访问：应用密码缺少所需权限
• 404 未找到：仓库、PR 或分支不存在
• 400 错误请求：参数或分支名称无效

原始 API 访问

对于脚本未覆盖的操作：

bash

GET 请求

curl -s -u $BITBUCKETUSERNAME:$BITBUCKETAPP_PASSWORD \
https://api.bitbucket.org/2.0/repositories/$BITBUCKET_WORKSPACE/my-repo | jq .

POST 请求

curl -s -X POST -u $BITBUCKETUSERNAME:$BITBUCKETAPP_PASSWORD \ -H Content-Type: application/json \ -d {content: {raw: 评论文本}} \ https://api.bitbucket.org/2.0/repositories/$BITBUCKET_WORKSPACE/my-repo/pullrequests/42/comments | jq .

API 文档：https://developer.atlassian.com/cloud/bitbucket/rest/