CNB 文档

简体中文

English

简体中文

English

外观

git:reviewer

复制页面

2538 字约 8 分钟

git:reviewer

配置评审人或处理人，给 PR 添加、删除评审人/处理人，可指定备选评审人/处理人范围。

术语约定：reviewer（评审人）指评审该 PR 的人，assignee（处理人，即 PR 界面里的「指派人」）指被指派处理该 PR 的人。二者相互独立，本任务可分别对两者增删。

适用事件

  • pull_request
  • pull_request.target
  • pull_request.update

pull_request 和 pull_request.update 事件下会检查触发者是否有权限操作评审人/处理人。 pull_request.target 事件下则不会。 对于跨仓提交的 PR，可能存在触发者无权限的情况。此时推荐使用 pull_request.target 事件。

参数

以下列表先概览 git:reviewer 的全部参数。

  • type：操作类型，添加/删除评审人或处理人
  • reviewers：要添加或删除的评审人/处理人
  • count：要添加的评审人/处理人数量
  • exclude：排除指定的用户
  • reviewersConfig：文件/内联评审人或处理人配置
  • role：可添加的成员角色范围
  • skip_on_wip：是否跳过 WIP 状态的 PR

各参数详细说明如下。

type

操作类型：

  • 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 为 add-reviewer 或 add-assignee 时有效。

reviewersConfig 支持以下两种格式，按需二选一（推荐使用 String 文件路径格式）：

格式取值说明
String（简单）配置文件的相对路径文件名（大小写不敏感）为 codeowners 时按 CODEOWNERS 格式解析，否则按 JSON 格式解析
内联对象（复杂）{ 文件路径: "用户名1,用户名2" }仅支持 JSON 格式，不支持 CODEOWNERS

其中：key 为文件相对路径（前缀匹配，即目录下的子文件也算命中）；value 为评审人或处理人的用户名，多个用英文逗号 , 分隔。

格式一：配置文件路径（简单格式，推荐）

传入配置文件相对路径。文件名（大小写不敏感）为 codeowners 时按 CODEOWNERS 格式解析，否则按 JSON 格式解析。

  • 按 JSON 格式解析：使用 .json 后缀
reviewers-config.json
{
  "./src": "name1,name2",
  ".cnb.yml": "name3"
}
  • 按 CODEOWNERS 格式解析：文件名为 codeowners（推荐路径 .cnb/codeowners）
.cnb/codeowners
# 通用规则写前，具体规则写后
*                       @global-team
*.js                    @fe-team
/src/frontend/          @frontend-owner
/src/frontend/auth.js   @security-team

CODEOWNERS 语法规则：

  • 每行格式为 <pattern> @owner1 @owner2 ...，pattern 遵循 gitignore 风格匹配。
  • 最后匹配的 pattern 优先级最高（通用规则写前，具体规则写后）。
  • # 开头的行为注释。
  • 无 owner 的 pattern 表示排除该路径。
  • 当前仅支持 @username 形式的 owner 解析为仓库成员；邮箱格式与 @org/team 会被忽略并打印告警。

注意

文件从任务执行时的 workspace 读取，对应当前 ref（PR 事件时为来源分支）， 与仓库级 CODEOWNERS 必须批准（从目标分支读取）是独立机制。

格式二：内联对象（复杂格式）

直接在 .cnb.yml 中内联配置「文件路径 → 评审人」映射，仅支持 JSON 格式，不支持 CODEOWNERS：

内联对象结构
{
  "./src": "name1,name2",
  ".cnb.yml": "name3"
}

与 reviewers 同时指定时的生效规则

reviewers 与 reviewersConfig 不是覆盖关系，而是取并集：

  1. 先按 reviewersConfig 匹配变更文件，得到一批候选人；再把这些候选人并入 reviewers 指定的名单，去重后作为统一的候选池。
  2. 再根据 count 从候选池中最终确定：
    • 未指定 count：候选池中的人全部被添加。
    • 指定了 count：从候选池中随机抽取 count 名添加（不足则全取）。

因此，公共评审人写在 reviewers，按目录/文件差异化的人员写在 reviewersConfig 即可，两边无需重复配置。

role

评审人或处理人可以添加的角色可选包括：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: String]: String
}

ROLE_TYPE

  • Enum<String>: Developer | Master | Owner

输出结果

添加评审人的输出结果：

{
  // 当前有效的评审人
  "reviewers": [],

  // reviewers 对应的 at 消息格式，方便发送通知
  "reviewersForAt": []
}

添加处理人的输出结果：

{
  // 当前有效的处理人
  "assignees": [],

  // assignees 对应的 at 消息格式，方便发送通知
  "assigneesForAt": []
}

配置样例

  • 添加评审人和处理人
.cnb.yml
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
  • 删除指定成员的评审人和处理人
.cnb.yml
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，指定文件被修改时添加评审人和处理人
.cnb.yml
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，在指定条件下将某些人添加为评审人或处理人
.cnb.yml
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
  • 随机选择一名负责人走查代码
.cnb.yml
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：

.cnb.yml
main:
  pull_request:
    - stages:
        - name: 按变更文件添加评审人
          type: git:reviewer
          options:
            type: add-reviewer
            # 配置文件相对路径，文件名以 .json 结尾按 JSON 解析
            reviewersConfig: reviewers-config.json
            count: 2

配套的配置文件：

reviewers-config.json
{
  "frontend": "loviselu,angelzou",
  "orange-ci": "loviselu,cristophwan",
  "infra": "robinzhxie,loviselu"
}
  • 使用 reviewersConfig（CODEOWNERS 格式），按变更文件匹配评审人
.cnb.yml
main:
  pull_request:
    - stages:
        - name: 按 CODEOWNERS 添加评审人
          type: git:reviewer
          options:
            type: add-reviewer
            # 文件名为 codeowners 时按 CODEOWNERS 格式解析
            reviewersConfig: .cnb/codeowners
.cnb/codeowners
# 通用规则写前，具体规则写后
*                       @global-team
/src/frontend/          @frontend-owner
/src/frontend/auth.js   @security-team
  • 使用 reviewersConfig（内联对象）并按变更文件匹配评审人
.cnb.yml
main:
  pull_request:
    - stages:
        - name: 按变更文件添加评审人
          type: git:reviewer
          options:
            type: add-reviewer
            reviewersConfig:
              "./src": "name1,name2"
              ".cnb.yml": "name3"
  • reviewers 与 reviewersConfig 同时使用（取并集）
.cnb.yml
main:
  pull_request:
    - stages:
        - name: 添加评审人
          type: git:reviewer
          options:
            type: add-reviewer
            # 按变更文件匹配的评审人
            reviewersConfig: reviewers-config.json
            # 公共评审人，与上面取并集后随机抽取 2 名
            reviewers: loviselu,robinzhxie,wenqiuli
            count: 2
  • 从当前仓库成员里选一名评审人评审
.cnb.yml
main:
  pull_request:
    - stages:
        - name: add reviewer
          type: git:reviewer
          options:
            type: add-reviewer-from-repo-members

最佳实践

自动随机分配评审人并通知

PR 随机选择 N 名评审者，发送通知到企业微信：

.cnb.yml
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}

评审通过后自动合并并通知

.cnb.yml
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}
© 2026 cnb.cool