git:reviewer
3419 字约 11 分钟
git:reviewer
配置评审人或处理人,给 PR 添加、删除评审人/处理人,可指定备选评审人/处理人范围。
术语约定:reviewer(评审人)指评审该 PR 的人,assignee(处理人,即 PR 界面里的「指派人」)指被指派处理该 PR 的人。二者相互独立,本任务可分别对两者增删。
使用场景:想让 PR 的评审人 / 处理人自动到位、而不必人工指派时使用——例如新建 PR 时 从仓库成员中随机添加一名评审人,或按文件变更范围指定对应负责人。 写脚本需要自行申请令牌、维护成员名单,git:reviewer 把这一步收敛成一个内置任务。
适用事件
pull_requestpull_request.targetpull_request.update
pull_request 和 pull_request.update 事件下会检查触发者是否有权限操作评审人/处理人。 pull_request.target 事件下则不会。 对于跨仓提交的 PR,可能存在触发者无权限的情况。此时推荐使用 pull_request.target 事件。
参数
以下列表先概览 git:reviewer 的全部参数。
- type:操作类型,添加/删除评审人或处理人
- reviewers:要添加或删除的评审人/处理人
- count:要添加的评审人/处理人数量
- exclude:排除指定的用户
- reviewersConfig:文件/内联评审人或处理人配置
- codeowners:为 PR 设置动态 codeowner 规则
- role:可添加的成员角色范围
- skip_on_wip:是否跳过 WIP 状态的 PR
各参数详细说明如下。
type
- type: REVIEW_OPERATION_TYPE
- required:
false - default:
add-reviewer
操作类型:
add-reviewer: 添加评审人,会从reviewers参数中选择指定数量的评审人add-reviewer-from-repo-members: 从仓库直接成员里选一名,添加为评审人add-reviewer-from-group-members: 从仓库父组织(直接上级组织)里选一名,添加为评审人add-reviewer-from-outside-collaborator-members: 从仓库的外部协作者里选一名,添加为评审人remove-reviewer: 从已有的评审人中删除指定的成员add-assignee: 添加处理人,添加reviewers参数传入的成员remove-assignee: 从已有的处理人中删除指定的成员
reviewers
- type:
Array<String>|String - required:
false
要添加或删除的评审人用户名。多个使用 , 或 ; 分隔。
type 为 add-reviewer、remove-reviewer、add-assignee、remove-assignee 时有效。
若同时配置了 reviewers 与 reviewersConfig,两者取并集作为候选池, 详见生效规则。
count
- type:
Number - required:
false
指定要添加的评审人或处理人数量,随机抽取指定数量的评审人或处理人。
- 当
type为add-reviewer或add-assignee时,count缺省值为reviewers的数量,即全部添加 - 当
type为add-reviewer-from-repo-members、add-reviewer-from-group-members或add-reviewer-from-outside-collaborator-members时:- 若目标分支为保护分支且设置了需要评审人批准,
count缺省值为需要批准的评审人数量 - 其他情况,
count缺省值为 1
- 若目标分支为保护分支且设置了需要评审人批准,
如果已有评审人或处理人的数量 < count ,那么补齐。
如果已有评审人或处理人的数量 >= count ,那么什么也不做。
exclude
- type:
Array<String>|String - required:
false
排除指定的用户。
reviewersConfig
- type: IReviewersConfig |
String - required:
false
按「变更文件」匹配评审人/处理人的配置。当变更的文件命中了配置里的路径规则时, 对应的人员会被纳入评审人/处理人的候选范围。
type 为 add-reviewer 或 add-assignee 时有效。
reviewersConfig 支持以下两种格式,按需二选一:
| 格式 | 取值 | 说明 |
|---|---|---|
String(简单) | JSON 配置文件的相对路径 | 按 JSON 解析 |
| 内联对象(复杂) | { 文件路径: "用户名1,用户名2" } | 直接在 .cnb.yml 中内联 |
其中 key 为文件相对路径(前缀匹配,目录下的子文件也算命中); value 为评审人或处理人的用户名,多个用英文逗号 , 分隔。
格式一:JSON 配置文件路径(简单格式)
传入配置文件相对路径,按 JSON 格式解析:
{
"./src": "name1,name2",
".cnb.yml": "name3"
}格式二:内联对象(复杂格式)
直接在 .cnb.yml 中内联配置「文件路径 → 评审人」映射:
{
"./src": "name1,name2",
".cnb.yml": "name3"
}与 reviewers 同时指定时的生效规则
reviewers 与 reviewersConfig 不是覆盖关系,而是取并集:
- 先按
reviewersConfig匹配变更文件得到一批候选人,再把这些候选人并入reviewers指定的名单,去重后作为统一的候选池。 - 再根据
count从候选池中最终确定:- 未指定
count:候选池中的人全部被添加。 - 指定了
count:从候选池中随机抽取count名添加(不足则全取)。
- 未指定
因此,公共评审人写在 reviewers,按目录/文件差异化的人员写在 reviewersConfig 即可,两边无需重复配置。
codeowners
- type: ICodeownersConfig |
String - required:
false
为 PR 设置动态 codeowner 规则:命中规则的 owner 批准后,PR 才能合并。
type 为 add-reviewer 时有效。
与 reviewers / reviewersConfig 的区别
这是两套互不影响的机制,用途完全不同:
reviewers / reviewersConfig | codeowners | |
|---|---|---|
| 效果 | 把人添加为 PR 的评审人 | 声明合并校验规则,不添加评审人 |
| 是否阻塞合并 | 否 | 是(需配合保护分支的「CODEOWNERS 必须批准」) |
受 count / exclude / role 影响 | 是 | 否 |
| 文件匹配时机 | CI 侧按本次变更文件匹配 | 规则整份下发,由服务端按变更文件匹配 |
因此,若既想让人收到评审通知、又要求其必须批准,需同时配置 reviewers 和 codeowners。
权限要求
要求触发者具备 Developer 及以上角色
流水线触发者需在本仓库具备 Developer 及以上角色。不满足时会跳过设置并打印告警, 不会导致构建失败。
跨仓库(fork)提交的 PR 中,触发者通常不是目标仓库成员,因此常因此跳过。 这类场景请改用仓库级 CODEOWNERS 文件。
优先级与替换语义
- 动态 codeowner 规则的优先级高于仓库 CODEOWNERS 文件:同一路径被两者命中时,动态规则生效。
- 一次任务执行会整份替换该 PR 上已有的动态规则,而非追加。
格式
支持以下两种格式,按需二选一(推荐使用 String 文件路径格式):
| 格式 | 取值 | 说明 |
|---|---|---|
String(简单) | 配置文件的相对路径 | 后缀为 .json(大小写不敏感)时按 JSON 解析,否则按 CODEOWNERS 解析 |
| 内联对象(复杂) | { pattern: "用户名1,用户名2" } | 仅支持 JSON 格式 |
与 reviewersConfig 的关键差异:这里的 key 是 CODEOWNERS pattern(gitignore 风格匹配), 而非普通文件路径前缀。
- 按 CODEOWNERS 格式解析:后缀不是
.json的文件(推荐路径.cnb/codeowners)
# 通用规则写前,具体规则写后
* @global-team
*.js @fe-team
/src/frontend/ @frontend-owner
/src/frontend/auth.js @security-team- 按 JSON 格式解析:后缀为
.json,key为 pattern,value为 owner 用户名,多个用英文逗号分隔
{
"/src/frontend/": "name1,name2",
".cnb.yml": "name3"
}CODEOWNERS 语法规则:
- 每行格式为
<pattern> @owner1 @owner2 ...,pattern遵循 gitignore 风格匹配。 - 最后匹配的
pattern优先级最高(通用规则写前,具体规则写后)。 #开头的行为注释。
与仓库级 CODEOWNERS 的差异
以下情况会导致构建失败
- 不支持无 owner 的 pattern。在仓库 CODEOWNERS 文件中,只写 pattern 不写 owner 表示 「排除该路径」;但动态规则无法表达该语义(保留反而会覆盖掉文件规则的 owner),配置后会直接报错。 排除语义请在仓库 CODEOWNERS 文件中配置。
- 某条规则的 owner 全部无法解析时报错。邮箱格式与
@org/team形式无法解析为仓库成员, 用户名也需对应仓库中具备Developer及以上角色的成员。
以下情况仅跳过对应规则并打印日志,不影响构建:
- owner 是本 PR 的提交者(不能作为自己 PR 的 codeowner)。
- owner 已被冻结(否则该 PR 将永远无法满足批准条件)。
配置文件的读取位置
文件从任务执行时的 workspace 读取,对应当前 ref(PR 事件时为来源分支), 与仓库级 CODEOWNERS 文件(从目标分支读取)是独立机制。
role
- type: ROLE_TYPE
- required:
false
评审人或处理人可以添加的角色可选包括:Developer、Master、Owner 如果选择 Developer,则可添加 Developer 及以上权限成员,包括 Developer、Master、Owner
skip_on_wip
- type:
Boolean - required:
false - default:
true
是否跳过 WIP 状态的 PR(PR 标题开头带有 [WIP] 标记),默认跳过 WIP 状态的 PR。
true: 当 PR 为WIP状态时,不会添加评审人或处理人。false: 当 PR 为WIP状态时,仍会添加评审人或处理人。
类型定义
REVIEW_OPERATION_TYPE
Enum<String>: add-reviewer | add-reviewer-from-repo-members | add-reviewer-from-group-members | add-reviewer-from-outside-collaborator-members | remove-reviewer | add-assignee | remove-assignee
IReviewersConfig
key 为文件相对路径,value 为用户名(多个用英文逗号分隔):
{
[key: String]: String
}ICodeownersConfig
key 为 CODEOWNERS pattern,value 为 owner 用户名(多个用英文逗号分隔):
{
[key: String]: String
}ROLE_TYPE
Enum<String>: Developer | Master | Owner
输出结果
添加评审人的输出结果:
{
// 当前有效的评审人
"reviewers": [],
// reviewers 对应的 at 消息格式,方便发送通知
"reviewersForAt": []
}添加处理人的输出结果:
{
// 当前有效的处理人
"assignees": [],
// assignees 对应的 at 消息格式,方便发送通知
"assigneesForAt": []
}配置样例
- 添加评审人和处理人
main:
pull_request:
- stages:
- name: 添加评审人
type: git:reviewer
options:
type: add-reviewer
reviewers: aaa;bbb
- name: 添加处理人
type: git:reviewer
options:
type: add-assignee
reviewers: ccc;ddd- 删除指定成员的评审人和处理人
main:
pull_request:
- stages:
- name: 删除评审人
type: git:reviewer
options:
type: remove-reviewer
reviewers: aaa
- name: 删除处理人
type: git:reviewer
options:
type: remove-assignee
reviewers: aaa- 结合
ifModify,指定文件被修改时添加评审人和处理人
main:
pull_request:
- stages:
- name: 改配置?需要特别 review
ifModify:
- ".cnb.yml"
- "configs/**"
type: git:reviewer
options:
type: add-reviewer
reviewers: bbb
- name: 改配置?需要特别处理
ifModify:
- ".cnb.yml"
- "configs/**"
type: git:reviewer
options:
type: add-assignee
reviewers: ccc- 结合
if,在指定条件下将某些人添加为评审人或处理人
main:
pull_request:
- stages:
- name: 下班时间发版本?需指定人评审。
if: |
[ $(date +%H) -ge 18 ]
type: git:reviewer
options:
type: add-reviewer
reviewers: bbb
- name: 下班时间发版本?需指定人处理。
if: |
[ $(date +%H) -ge 18 ]
type: git:reviewer
options:
type: add-assignee
reviewers: ccc- 随机选择一名负责人走查代码
main:
pull_request:
- stages:
- name: random
image: tencentcom/random
settings:
from:
- aaa
- bbb
exports:
result: CURR_REVIEWER
- name: show CURR_REVIEWER
script: echo ${CURR_REVIEWER}
- name: add reviewer
type: git:reviewer
options:
type: add-reviewer
reviewers: ${CURR_REVIEWER}- 使用
reviewersConfig(配置文件路径),按变更文件匹配评审人
完整的 .cnb.yml:
main:
pull_request:
- stages:
- name: 按变更文件添加评审人
type: git:reviewer
options:
type: add-reviewer
# 配置文件相对路径,文件名以 .json 结尾按 JSON 解析
reviewersConfig: reviewers-config.json
count: 2配套的配置文件:
{
"frontend": "loviselu,angelzou",
"orange-ci": "loviselu,cristophwan",
"infra": "robinzhxie,loviselu"
}- 使用
codeowners(CODEOWNERS 格式),按变更文件要求 owner 批准
main:
pull_request:
- stages:
- name: 设置动态 codeowner
type: git:reviewer
options:
type: add-reviewer
# 后缀不是 .json 时按 CODEOWNERS 格式解析
codeowners: .cnb/codeowners# 通用规则写前,具体规则写后
* @global-team
/src/frontend/ @frontend-owner
/src/frontend/auth.js @security-team- 使用
codeowners(内联对象),key为 CODEOWNERS pattern
main:
pull_request:
- stages:
- name: 设置动态 codeowner
type: git:reviewer
options:
type: add-reviewer
codeowners:
"/src/frontend/": "name1,name2"
".cnb.yml": "name3"- 使用
reviewersConfig(内联对象)并按变更文件匹配评审人
main:
pull_request:
- stages:
- name: 按变更文件添加评审人
type: git:reviewer
options:
type: add-reviewer
reviewersConfig:
"./src": "name1,name2"
".cnb.yml": "name3"reviewers与reviewersConfig同时使用(取并集)
main:
pull_request:
- stages:
- name: 添加评审人
type: git:reviewer
options:
type: add-reviewer
# 按变更文件匹配的评审人
reviewersConfig: reviewers-config.json
# 公共评审人,与上面取并集后随机抽取 2 名
reviewers: loviselu,robinzhxie,wenqiuli
count: 2- 从当前仓库成员里选一名评审人评审
main:
pull_request:
- stages:
- name: add reviewer
type: git:reviewer
options:
type: add-reviewer-from-repo-members最佳实践
自动随机分配评审人并通知
PR 随机选择 N 名评审者,发送通知到企业微信:
main:
pull_request:
- stages:
- name: add reviewer
type: git:reviewer
options:
reviewers: aaa,bbb,ccc,ddd
count: 2
exports:
reviewersForAt: CURR_REVIEWER_FOR_AT
- name: notify
image: tencentcom/wecom-message
settings:
msgType: markdown
robot: "your-robot-key"
content: |
> ${CURR_REVIEWER_FOR_AT}
> ${CNB_PULL_REQUEST_TITLE}
> [${CNB_EVENT_URL}](${CNB_EVENT_URL})
> from ${CNB_BUILD_USER}评审通过后自动合并并通知
main:
review:
- stages:
- name: CR 通过后自动合并
type: git:auto-merge
options:
mergeType: squash
removeSourceBranch: true
exports:
reviewedBy: REVIEWED_BY
- name: notify
image: tencentcom/wecom-message
settings:
msgType: markdown
robot: "your-robot-key"
content: |
> CR 通过后自动合并 <@${CNB_BUILD_USER}>
> ${CNB_PULL_REQUEST_TITLE}
> [${CNB_EVENT_URL}](${CNB_EVENT_URL})
> ${REVIEWED_BY}