企业官网建设流程全解析

• CI/CD
• 代码评审
• 开发工具

本指南基于 danger-js 仓库中 docs/usage/bitbucket_cloud.html.md 编写，讲解如何让 Danger 在 BitBucket Cloud 的 Pull Request 上自动发布代码审查反馈。你将掌握三种认证方式（用户名密码、OAuth、仓库访问令牌）的完整配置、danger.bitbucket_cloud对象的结构与用法，以及底层 API 凭证解析与评论发布机制，可直接应用到自己的 CI 流水线中。

前置准备：为 Danger 创建专用账号

要让 Danger 在 BitBucket Cloud 上代发评论，首先需要创建一个专门给 Danger 使用的 BitBucket Cloud 账号。这个账号不参与实际开发，只负责以机器人的身份读取 Pull Request 信息、写入审查评论、更新构建状态。所有后续的认证凭证（用户名、密码、OAuth 或仓库访问令牌）都归属于该账号。

三种认证方式与环境变量配置

在 CI 上运行 Danger 时，需要把以下环境变量按需配置到构建环境中。三种方式可以任选其一，源码中的解析顺序是 OAuth 优先、其次用户名密码、最后仓库访问令牌（详见 BitBucketCloudAPI.ts 的bitbucketCloudCredentialsFromEnv）。

方式一：用户名 + 密码

需要设置两个环境变量：

• DANGER_BITBUCKETCLOUD_USERNAME：用于代发评论的账号用户名，可在 BitBucket 账户页面查看。
• DANGER_BITBUCKETCLOUD_PASSWORD：该账号的密码。官方建议使用App passwords（应用专用密码），并为其授予两项权限：Read Pull Requests（读取 Pull Request）与Read Account（读取账户信息）。

从源码看，用户名密码方式会在每次 API 请求时通过Authorization: Basic <base64(username:password)>头进行认证；同时会调用https://api.bitbucket.org/2.0/user获取当前用户的 UUID，用于识别 Danger 自己的评论。

方式二：OAuth Key + Secret

创建 OAuth consumer 的步骤如下：

1. 打开 BitBucket Cloud 官网；
2. 进入Settings > OAuth > Add consumer；
3. 将 Callback URL 设置为https://bitbucket.org/site/oauth2/authorize；
4. 勾选Read Pull requests与Read Account两项权限。

然后配置两个环境变量：

• DANGER_BITBUCKETCLOUD_OAUTH_KEY：页面上显示的Key，即 consumer key；
• DANGER_BITBUCKETCLOUD_OAUTH_SECRET：页面上显示的Secret，即 consumer secret。

底层实现中（BitBucketCloudAPI.ts），Danger 会用 OAuth Key/Secret 组成 Basic 凭证，向https://bitbucket.org/site/oauth2/access_token发起grant_type=client_credentials的 POST 请求换取access_token，之后所有 API 调用都携带Authorization: Bearer <access_token>。

方式三：仓库访问令牌（Repository Access Token）

创建方式：

1. 打开目标仓库的 URL；
2. 进入Settings > Security > Access Tokens > Create Repository Access Token；
3. 为令牌命名，并勾选Pull requests: write权限范围。

对应环境变量：

• DANGER_BITBUCKETCLOUD_REPO_ACCESSTOKEN：创建好的仓库访问令牌。

源码中该方式同样使用Authorization: Bearer <accessToken>头进行认证。需要注意的是，仓库访问令牌的权限局限于单个仓库，适合只在某一个仓库中运行 Danger 的场景。

可选：DANGER_BITBUCKETCLOUD_UUID

仓库还支持可选的DANGER_BITBUCKETCLOUD_UUID环境变量，用于显式指定 Danger 机器人的用户 UUID。源码规定该值必须用花括号包裹（例如{1234-1234-1234-1234}），否则会抛出DANGER_BITBUCKETCLOUD_UUID must be wraped with brackets错误（见 BitBucketCloudAPI.ts）。Danger 用它来过滤出自己发布过的评论，实现"结果更新"与"问题修复后删除评论"。

凭证解析的优先级与报错

bitbucketCloudCredentialsFromEnv的判定逻辑为：

1. 若设置了DANGER_BITBUCKETCLOUD_OAUTH_KEY，则要求同时存在DANGER_BITBUCKETCLOUD_OAUTH_SECRET，否则报DANGER_BITBUCKETCLOUD_OAUTH_SECRET is not set；
2. 否则若设置了DANGER_BITBUCKETCLOUD_USERNAME，则要求同时存在DANGER_BITBUCKETCLOUD_PASSWORD，否则报DANGER_BITBUCKETCLOUD_PASSWORD is not set；
3. 否则若设置了DANGER_BITBUCKETCLOUD_REPO_ACCESSTOKEN，则使用仓库令牌；
4. 三者皆无时抛出错误：Either DANGER_BITBUCKETCLOUD_OAUTH_KEY, DANGER_BITBUCKETCLOUD_USERNAME or DANGER_BITBUCKETCLOUD_REPO_ACCESSTOKEN is not set。

此外，当 API 请求返回 4xx 状态码时，源码会附加提示(Have you allowed permission 'account' for this credential?)或(Have you set DANGER_BITBUCKETCLOUD_USERNAME or DANGER_BITBUCKETCLOUD_OAUTH_KEY?)，用于引导排查权限配置问题（BitBucketCloudAPI.ts 与 BitBucketCloudAPI.ts）。

在 CI 中启用 Danger：以 Bitbucket Pipelines 为例

仓库自带了 Bitbucket Pipelines 的 CI 集成实现（BitbucketPipelines.ts），它通过识别BITBUCKET_BUILD_NUMBER（判定是否在 Pipelines 中）以及BITBUCKET_GIT_HTTP_ORIGIN、BITBUCKET_REPO_OWNER、BITBUCKET_REPO_SLUG、BITBUCKET_PR_ID（判定是否为 PR 构建）来自动启用。典型的bitbucket-pipelines.yml配置如下：

image: node:10.15.0 pipelines: pull-requests: "**": - step: caches: - node script: - export LANG="C.UTF-8" - yarn install - yarn danger ci definitions: caches: node: node_modules

要点说明：

• 在pull-requests流水线中运行danger ci，Danger 会基于当前 PR 环境生成 DSL 并执行 Dangerfile；
• 通过caches缓存node_modules可提升构建速度；
• 在 Bitbucket Pipelines 的仓库设置（Repository variables）中，把上一节的环境变量（如DANGER_BITBUCKETCLOUD_USERNAME/DANGER_BITBUCKETCLOUD_PASSWORD或 OAuth 组合）配置为受保护的变量，避免明文泄露。

其他 CI 系统（如 Jenkins、CircleCI 等）也可使用，Danger 会自动从环境中识别 CI 来源（见 get_ci_source.ts 的getCISourceForEnv），只要对应的 CI 环境变量存在即可。

在 Dangerfile 中使用 danger.bitbucket_cloud

完成认证与 CI 配置后，Danger 会在每次运行时向 BitBucket Cloud API 拉取当前 PR 的数据，组装成完整的danger.bitbucket_cloud对象注入到 Dangerfile 中。一个最小示例：

import { danger, warn } from "danger" if (danger.bitbucket_cloud.pr.title.includes("WIP")) { warn("PR is considered WIP") }

当 PR 标题包含 "WIP" 时，Danger 会在 PR 上发布一条 warning 评论。

DSL 对象全景

danger.bitbucket_cloud对象包含以下五个核心字段（类型定义见 BitBucketCloudDSL.ts）：

danger.bitbucket_cloud. /** 当前 PR 与仓库元数据 */ metadata: RepoMetaData /** PR 元数据（标题、状态、来源/目标分支等） */ pr: BitBucketCloudPRDSL /** 与该 PR 关联的提交列表 */ commits: BitBucketCloudCommit[] /** 该 PR 上的评论 */ comments: BitBucketCloudPRComment[] /** 该 PR 的活动记录（OPENING、COMMENTING、CLOSING、MERGING、UPDATING 等） */ activities: BitBucketCloudPRActivity[]

这些数据在 BitBucketCloud.ts 的getPlatformReviewDSLRepresentation中通过一次并发拉取组装：getPullRequestInfo()、getPullRequestCommits()、getPullRequestComments()、getPullRequestActivities()，均使用 Bitbucket Cloud API 2.0 的分页接口（/repositories/{workspace}/{repo}/pullrequests/{id}/...）。如果获取 PR 信息失败，Danger 会设置退出码 1 并提示 "Could not find pull request information, perhaps Danger does not have permission to access the repo."。

关键子对象详解

RepoMetaData（RepoMetaData.ts）：仅含两个字段——repoSlug（形如workspace/repo_slug的完整路径）与pullRequestID（PR 的数字 ID）。

BitBucketCloudPRDSL（BitBucketCloudDSL.ts）包含：

• id、title、description：PR 编号、标题、描述；
• state："OPEN" | "MERGED" | "DECLINED" | "SUPERSEDED"，即 PR 当前状态；
• created_on/updated_on：创建与更新时间（ISO 8601 格式）；
• source/destination：BitBucketCloudMergeRef，含commit.hash、branch.name、repository（仓库名、full_name、uuid）；
• author：PR 创建者（含uuid、display_name、nickname、account_id）；
• reviewers：受邀审查者列表；participants：参与人员（含role: "REVIEWER" | "PARTICIPANT"与approved布尔值）；
• links：指向 decline、commits、comments、merge、diff、approve、statuses 等端点的超媒体链接。

BitBucketCloudCommit（BitBucketCloudDSL.ts）：hash（SHA）、author（含raw: "Foo Bar <foo@bar.com>"格式的原始作者串与用户信息）、date、message、parents（父提交哈希数组）、links。在 BitBucketCloudGit.ts 中，这些提交会被转换为通用的GitCommit，供danger.git使用。

BitBucketCloudPRComment（BitBucketCloudDSL.ts）：评论内容content（raw/markup/html）、user、created_on、updated_on、inline（可选的行内定位：to、from、path）等。注意 Danger 的审查结果评论通过content.raw中包含的danger-id-<dangerID>;签名来识别，见 bitbucketCloudTemplate.ts。

借助 API 对象扩展能力

danger.bitbucket_cloud上还挂载了一个已认证的api对象（BitBucketCloudDSL.ts），允许你在 Dangerfile 里直接调用 Bitbucket Cloud 的 REST API：

• getFileContents(filePath, repoSlug?, refspec?)：读取仓库中某个文件在指定 commit 下的内容（默认取当前 PR 的 source 分支与最新 commit）；
• get(path, headers?, suppressErrors?)、post(path, headers?, body?, suppressErrors?)、put(...)、delete(...)：对 Bitbucket Cloud API 2.0 发起 HTTP 请求。

例如，可以读取 PR 中修改的某个配置文件来做一致性校验：

import { danger, fail } from "danger" const lockfile = await danger.bitbucket_cloud.api.getFileContents("yarn.lock") if (!lockfile) { fail("yarn.lock 不存在或无法读取") }

Danger 评论的生命周期：发布、更新与清理

Danger 在 BitBucket Cloud 上的评论管理基于danger-id签名机制（BitBucketCloud.ts 的updateOrCreateComment）：

• 首次运行：若该 PR 上不存在 Danger 的评论，则新建一条主评论；
• 再次运行：找到已有的主评论并就地更新（PUT），同时删除重复的历史评论，保证 PR 上始终只有一条最新结果；
• 当所有问题都修复后：删除整条主评论（deleteMainComment），让 PR 保持整洁。

评论内容的渲染由 bitbucketCloudTemplate.ts 完成：无 Fails 与 Warnings 时输出:tada: All green.及随机表扬语；有问题时按 Fails、Warnings、Messages 三个 Markdown 表格分区展示，末尾附带 "Generated by …" 签名。模板支持 BitBucket Cloud 的表情符号（:x:、:warning:、:sparkles:、:tada:等）。

此外，BitBucket Cloud 平台还支持行内评论（supportsInlineComments()返回 true）。当在 Dangerfile 中对具体文件行使用message/warn/fail并附带文件路径时，Danger 会调用postInlinePRComment在对应代码行上发布评论，并通过inline字段（to行号 +path文件路径）定位（见 BitBucketCloudAPI.ts）。

构建状态上报

Danger 还能把检查结果以build status的形式挂到 PR 的 source commit 上（updateStatus，见 BitBucketCloud.ts），映射关系为：

状态请求会 POST 到{baseURL}/repositories/{repo}/commit/{commitId}/statuses/build，默认 name 为Danger、key 为danger.systems；当设置了dangerID时 name/key 会替换为该 ID。这让你可以在 BitBucket 的 PR 页面上直接看到 Danger 的检查通过/失败状态，与 CI 的 Pipelines 结果并列展示。

故障排查速查

• 提示找不到 PR 信息：多为 Danger 使用的账号缺少 Read Pull requests 权限，或仓库访问令牌未勾选相应 scope；
• 认证报错 401/403 并提示 permission 'account'：说明凭证未授予 Read Account 权限（用户名密码方式尤其需要确认 App password 勾选了 Read Account）；
• DANGER_BITBUCKETCLOUD_UUID 报错：UUID 必须以{开头、}结尾；
• 评论未更新：确认 CI 中每次运行都使用了相同的dangerID（默认基于 commit 生成），Danger 依靠它识别自己的旧评论。

以上配置与行为的实现依据，可进一步查阅 BitBucketCloud.ts、BitBucketCloudAPI.ts、BitBucketCloudDSL.ts 以及对应的测试用例 _bitbucket_cloud.test.ts 与 _bitbucket_cloud_api.test.ts，这些测试用例完整覆盖了凭证构造、API 端点调用与评论过滤逻辑，可作为集成验证的参考。

• CI/CD
• 代码评审
• 开发工具