---
url: /zh/build/internal-steps/git/reviewer.md
---
`git:reviewer`

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

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

* [适用事件](#git-reviewer-applicable-events)
* [参数](#git-reviewer-parameters)
* [输出结果](#git-reviewer-output)
* [配置样例](#git-reviewer-configuration-examples)
* [最佳实践](#git-reviewer-best-practices)

## 适用事件 {#git-reviewer-applicable-events}

* `pull_request`
* `pull_request.target`
* `pull_request.update`

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

## 参数 {#git-reviewer-parameters}

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

* [type](#git-reviewer-parameters-type)：操作类型，添加/删除评审人或处理人
* [reviewers](#git-reviewer-parameters-reviewers)：要添加或删除的评审人/处理人
* [count](#git-reviewer-parameters-count)：要添加的评审人/处理人数量
* [exclude](#git-reviewer-parameters-exclude)：排除指定的用户
* [reviewersConfig](#git-reviewer-parameters-reviewersConfig)：文件/内联评审人或处理人配置
* [role](#git-reviewer-parameters-role)：可添加的成员角色范围
* [skip\_on\_wip](#git-reviewer-parameters-skip_on_wip)：是否跳过 WIP 状态的 PR

各参数详细说明如下。

### type {#git-reviewer-parameters-type}

* type: [REVIEW\_OPERATION\_TYPE](#git-reviewer-parameters-type-definitions-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 {#git-reviewer-parameters-reviewers}

* type: `Array<String>` | `String`
* required: `false`

要添加或删除的评审人用户名。多个使用 `,` 或 `;` 分隔。

`type` 为 `add-reviewer`、`remove-reviewer`、`add-assignee`、`remove-assignee` 时有效。

若同时配置了 `reviewers` 与 `reviewersConfig`，两者取**并集**作为候选池，详见[生效规则](#git-reviewer-parameters-reviewersConfig-merge)。

### count {#git-reviewer-parameters-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 {#git-reviewer-parameters-exclude}

* type: `Array<String>` | `String`
* required: `false`

排除指定的用户。

### reviewersConfig {#git-reviewer-parameters-reviewersConfig}

* type: [IReviewersConfig](#git-reviewer-parameters-type-definitions-IReviewersConfig) | `String`
* required: `false`

按「变更文件」匹配评审人/处理人的配置。当变更的文件命中了配置里的路径规则时，
对应的人员会被纳入评审人/处理人的候选范围。

`type` 为 `add-reviewer` 或 `add-assignee` 时有效。

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

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

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

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

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

* 按 JSON 格式解析：使用 `.json` 后缀

```json title="reviewers-config.json"
{
  "./src": "name1,name2",
  ".cnb.yml": "name3"
}
```

* 按 CODEOWNERS 格式解析：文件名为 `codeowners`（推荐路径 `.cnb/codeowners`）

```text title=".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` 会被忽略并打印告警。

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

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

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

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

#### 与 `reviewers` 同时指定时的生效规则 {#git-reviewer-parameters-reviewersConfig-merge}

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

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

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

### role {#git-reviewer-parameters-role}

* type: [ROLE\_TYPE](#git-reviewer-parameters-type-definitions-ROLE_TYPE)
* required: `false`

评审人或处理人可以添加的角色可选包括：`Developer`、`Master`、`Owner`
如果选择 `Developer`，则可添加 `Developer` 及以上权限成员，包括
`Developer`、`Master`、`Owner`

### skip\_on\_wip {#git-reviewer-parameters-skip\_on\_wip}

* type: `Boolean`
* required: `false`
* default: `true`

是否跳过 `WIP` 状态的 PR（PR 标题开头带有 `[WIP]` 标记），默认跳过 `WIP` 状态的 PR。

* `true`: 当 PR 为 `WIP` 状态时，不会添加评审人或处理人。
* `false`: 当 PR 为 `WIP` 状态时，仍会添加评审人或处理人。

### 类型定义 {#git-reviewer-parameters-type-definitions}

#### REVIEW\_OPERATION\_TYPE {#git-reviewer-parameters-type-definitions-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 {#git-reviewer-parameters-type-definitions-IReviewersConfig}

```javascript
{
    [key: String]: String
}
```

#### ROLE\_TYPE {#git-reviewer-parameters-type-definitions-ROLE\_TYPE}

* `Enum<String>`: Developer | Master | Owner

## 输出结果 {#git-reviewer-output}

添加评审人的输出结果：

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

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

添加处理人的输出结果：

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

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

## 配置样例 {#git-reviewer-configuration-examples}

* 添加评审人和处理人

```yaml title=".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
```

* 删除指定成员的评审人和处理人

```yaml title=".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`，指定文件被修改时添加评审人和处理人

```yaml title=".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`，在指定条件下将某些人添加为评审人或处理人

```yaml title=".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
```

* 随机选择一名负责人走查代码

```yaml title=".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`：

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

配套的配置文件：

```json title="reviewers-config.json"
{
  "frontend": "loviselu,angelzou",
  "orange-ci": "loviselu,cristophwan",
  "infra": "robinzhxie,loviselu"
}
```

* 使用 `reviewersConfig`（CODEOWNERS 格式），按变更文件匹配评审人

```yaml title=".cnb.yml"
main:
  pull_request:
    - stages:
        - name: 按 CODEOWNERS 添加评审人
          type: git:reviewer
          options:
            type: add-reviewer
            # 文件名为 codeowners 时按 CODEOWNERS 格式解析
            reviewersConfig: .cnb/codeowners
```

```text title=".cnb/codeowners"
# 通用规则写前，具体规则写后
*                       @global-team
/src/frontend/          @frontend-owner
/src/frontend/auth.js   @security-team
```

* 使用 `reviewersConfig`（内联对象）并按变更文件匹配评审人

```yaml title=".cnb.yml"
main:
  pull_request:
    - stages:
        - name: 按变更文件添加评审人
          type: git:reviewer
          options:
            type: add-reviewer
            reviewersConfig:
              "./src": "name1,name2"
              ".cnb.yml": "name3"
```

* `reviewers` 与 `reviewersConfig` 同时使用（取并集）

```yaml title=".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
```

* 从当前仓库成员里选一名评审人评审

```yaml title=".cnb.yml"
main:
  pull_request:
    - stages:
        - name: add reviewer
          type: git:reviewer
          options:
            type: add-reviewer-from-repo-members
```

## 最佳实践 {#git-reviewer-best-practices}

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

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

```yaml title=".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}
```

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

```yaml title=".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}
```