git:reviewer
About 2492 wordsAbout 8 min
git:reviewer
Configure reviewers or assignees to add or remove reviewers/assignees to a PR, with the option to specify a range of alternative reviewers/assignees.
Terminology: reviewer is the person who reviews the PR, while assignee is the person assigned to handle the PR (shown as the assignee on the PR page). The two are independent, and this task can add/remove either of them separately.
When to use it: use it when reviewers/assignees should be assigned automatically instead of by hand - for example adding a random reviewer from the repository members when a PR is opened, or picking the owner of the affected files. Scripting this yourself means requesting a token and maintaining the member list, so git:reviewer folds it into a single built-in task.
Applicable Events
pull_requestpull_request.targetpull_request.update
Under pull_request and pull_request.update events, the trigger will check if the initiator has permission to operate on reviewers/assignees. This check is not performed under the pull_request.target event. For PRs submitted across repositories, there may be cases where the initiator lacks permission. In such cases, it is recommended to use the pull_request.target event.
Parameters
The list below gives an overview of all git:reviewer parameters.
- type: Operation type; add/remove reviewers or assignees
- reviewers: Reviewers or assignees to add or remove
- count: Number of reviewers/assignees to add
- exclude: Exclude specified users
- reviewersConfig: File-based or inline reviewer/assignee config
- codeowners: Set dynamic codeowner rules for the PR
- role: Role scope of members that can be added
- skip_on_wip: Whether to skip PRs in the WIP state
Detailed descriptions for each parameter are provided below.
type
- type: REVIEW_OPERATION_TYPE
- required:
false - default:
add-reviewer
Operation type:
add-reviewer: Add reviewers, selecting a specified number of reviewers from thereviewersparameteradd-reviewer-from-repo-members: Select one reviewer directly from repository members and add them as a revieweradd-reviewer-from-group-members: Select one reviewer from the repository's parent organization (direct superior organization) and add them as a revieweradd-reviewer-from-outside-collaborator-members: Select one reviewer from the repository's external collaborators and add them as a reviewerremove-reviewer: Remove specified members from existing reviewersadd-assignee: Add assignees, adding members specified in thereviewersparameterremove-assignee: Remove specified members from existing assignees
reviewers
- type:
Array<String>|String - required:
false
Usernames of reviewers to add or remove. Multiple usernames can be separated by , or ;.
Effective when type is add-reviewer, remove-reviewer, add-assignee, or remove-assignee.
If both reviewers and reviewersConfig are set, they are merged as a union; see Precedence.
count
- type:
Number - required:
false
Specify the number of reviewers or assignees to add, randomly selecting the specified number of reviewers or assignees.
- When
typeisadd-revieweroradd-assignee, the default value forcountis the number ofreviewers, meaning all are added. - When
typeisadd-reviewer-from-repo-members,add-reviewer-from-group-members, oradd-reviewer-from-outside-collaborator-members:- If the target branch is a protected branch with a requirement for reviewer approvals, the default value for
countis the number of reviewers required for approval. - In other cases, the default value for
countis 1.
- If the target branch is a protected branch with a requirement for reviewer approvals, the default value for
If the number of existing reviewers or assignees is < count, then fill up to the specified count.
If the number of existing reviewers or assignees is >= count, then no action is taken.
exclude
- type:
Array<String>|String - required:
false
Exclude specified users.
reviewersConfig
- type: IReviewersConfig |
String - required:
false
Configuration that matches reviewers/assignees by changed files. When a changed file matches a path rule in the config, the corresponding users are included in the candidate scope of reviewers/assignees.
Effective when type is add-reviewer or add-assignee.
reviewersConfig supports the following two formats. Pick one as needed:
| Format | Value | Description |
|---|---|---|
String (simple) | Relative path to a JSON config file | Parsed as JSON |
| Inline object (complex) | { "file path": "user1,user2" } | Inlined directly in .cnb.yml |
Here, the key is the relative file path (prefix match, so subfiles under a directory also match), and the value is the usernames of reviewers or assignees, separated by commas ,.
Format 1: JSON config file path (simple format)
Pass the relative path to the configuration file, which is parsed as JSON:
{
"./src": "name1,name2",
".cnb.yml": "name3"
}Format 2: Inline object (complex format)
Configure the "file path -> reviewer" mapping inline in .cnb.yml:
{
"./src": "name1,name2",
".cnb.yml": "name3"
}Precedence when combined with reviewers
reviewers and reviewersConfig are merged (union), not overridden:
- First,
reviewersConfigmatches the changed files to produce a set of candidates; these candidates are then merged into the list specified byreviewers, deduplicated into a single candidate pool. countthen decides the final result:- If
countis not specified: all users in the candidate pool are added. - If
countis specified:countusers are randomly sampled from the candidate pool (all of them if there are fewer thancount).
- If
Therefore, put common reviewers in reviewers and per-directory/file reviewers in reviewersConfig; there is no need to duplicate entries on both sides.
codeowners
- type: ICodeownersConfig |
String - required:
false
Set dynamic codeowner rules for the PR: the matched owners must approve before the PR can be merged.
Effective when type is add-reviewer.
Difference from reviewers / reviewersConfig
These are two independent mechanisms serving entirely different purposes:
reviewers / reviewersConfig | codeowners | |
|---|---|---|
| Effect | Adds users as PR reviewers | Declares merge check rules; adds no reviewer |
| Blocks merging | No | Yes (with "CODEOWNERS approval required" on a protected branch) |
Affected by count / exclude / role | Yes | No |
| When files are matched | On the CI side, against the current changed files | The whole rule set is sent and matched on the server side |
Therefore, to both notify someone as a reviewer and require their approval, configure reviewers and codeowners together.
Permission requirement
Requires the Developer role or above
The pipeline trigger user must have the Developer role or above in this repository. Otherwise the operation is skipped with a warning, and the build does not fail.
For pull requests from forked repositories, the trigger user is usually not a member of the target repository and is therefore commonly skipped. Use the repository-level CODEOWNERS file for those scenarios.
Priority and replacement semantics
- Dynamic codeowner rules take precedence over the repository CODEOWNERS file: when both match the same path, the dynamic rule wins.
- A single task run replaces the whole set of existing dynamic rules on the PR rather than appending to it.
Formats
The following two formats are supported. Pick one as needed (the String file-path format is recommended):
| Format | Value | Description |
|---|---|---|
String (simple) | Relative path to a config file | Parsed as JSON when the extension is .json (case-insensitive); otherwise as CODEOWNERS |
| Inline object (complex) | { "pattern": "user1,user2" } | JSON format only |
The key difference from reviewersConfig: here the key is a CODEOWNERS pattern (gitignore-style matching), not a plain file path prefix.
- Parsed as CODEOWNERS: any file without the
.jsonextension (recommended path:.cnb/codeowners)
# Write general rules first, specific rules last
* @global-team
*.js @fe-team
/src/frontend/ @frontend-owner
/src/frontend/auth.js @security-team- Parsed as JSON: the file has the
.jsonextension; thekeyis a pattern and thevaluelists owner usernames separated by commas
{
"/src/frontend/": "name1,name2",
".cnb.yml": "name3"
}CODEOWNERS syntax rules:
- Each line is
<pattern> @owner1 @owner2 ...;patternfollows gitignore-style matching. - The last matching pattern wins (write general rules first, specific rules last).
- Lines starting with
#are comments.
Differences from the repository-level CODEOWNERS
The following cases fail the build
- Patterns without any owner are not supported. In the repository CODEOWNERS file, a pattern with no owner means "exclude this path"; dynamic rules cannot express that semantics (keeping such a rule would instead override the owners of the file rule), so configuring one fails. Configure the exclusion in the repository CODEOWNERS file instead.
- A rule whose owners all fail to resolve fails the build. Email-format and
@org/teamowners cannot be resolved to repository members, and usernames must refer to members holding theDeveloperrole or above in the repository.
The following cases only skip the corresponding rule with a log entry and do not affect the build:
- The owner is the author of this PR (one cannot be a codeowner of their own PR).
- The owner is frozen (otherwise the PR could never satisfy the approval requirement).
Where the config file is read from
The file is read from the workspace at task execution time, which corresponds to the current ref (for PR events, this is the source branch). This is an independent mechanism from the repository-level CODEOWNERS file, which is read from the base branch.
role
- type: ROLE_TYPE
- required:
false
Roles that reviewers or assignees can have include: Developer, Master, Owner. If Developer is selected, members with Developer and higher permissions can be added, including Developer, Master, Owner.
skip_on_wip
- type:
Boolean - required:
false - default:
true
Whether to skip the operation when the pull request is a WIP pull request. The default value is true.
true: the operation will be skipped when the pull request is a WIP pull request.false: the operation will be performed regardless of whether the pull request is a WIP pull request.
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
The key is a relative file path and the value lists usernames separated by commas:
{
[key: String]: String
}ICodeownersConfig
The key is a CODEOWNERS pattern and the value lists owner usernames separated by commas:
{
[key: String]: String
}ROLE_TYPE
Enum<String>: Developer | Master | Owner
Output Results
Output result for adding reviewers:
{
"reviewers": [],
"reviewersForAt": []
}Output result for adding assignees:
{
"assignees": [],
"assigneesForAt": []
}Configuration Examples
- Adding reviewers and assignees:
main:
pull_request:
- stages:
- name: Add Reviewers
type: git:reviewer
options:
type: add-reviewer
reviewers: aaa;bbb
- name: Add Assignees
type: git:reviewer
options:
type: add-assignee
reviewers: ccc;ddd- Delete reviewers or assignees:
main:
pull_request:
- stages:
- name: Remove Reviewers
type: git:reviewer
options:
type: remove-reviewer
reviewers: aaa
- name: Remove Assignees
type: git:reviewer
options:
type: remove-assignee
reviewers: aaa- Combining with
ifModify, adding reviewers and assignees when specific files are modified:
main:
pull_request:
- stages:
- name: Review for Configuration Changes
ifModify:
- ".cnb.yml"
- "configs/**"
type: git:reviewer
options:
type: add-reviewer
reviewers: bbb
- name: Assign for Configuration Changes
ifModify:
- ".cnb.yml"
- "configs/**"
type: git:reviewer
options:
type: add-assignee
reviewers: ccc- Combining with
if, adding specific reviewers or assignees under certain conditions:
main:
pull_request:
- stages:
- name: Release after Hours? Requires Reviewers.
if: |
[ $(date +%H) -ge 18 ]
type: git:reviewer
options:
type: add-reviewer
reviewers: bbb
- name: Release after Hours? Requires Assignees.
if: |
[ $(date +%H) -ge 18 ]
type: git:reviewer
options:
type: add-assignee
reviewers: ccc- Randomly selecting one person to review the code:
main:
pull_request:
- stages:
- name: Random Selection
image: tencentcom/random
settings:
from:
- aaa
- bbb
exports:
result: CURR_REVIEWER
- name: Show Current Reviewer
script: echo ${CURR_REVIEWER}
- name: Add Reviewer
type: git:reviewer
options:
type: add-reviewer
reviewers: ${CURR_REVIEWER}- Using
reviewersConfig(config file path) to match reviewers by changed files:
The complete .cnb.yml:
main:
pull_request:
- stages:
- name: Add Reviewers by Changed Files
type: git:reviewer
options:
type: add-reviewer
# Relative path to the config file; parsed as JSON when it ends with .json
reviewersConfig: reviewers-config.json
count: 2The accompanying config file:
{
"frontend": "loviselu,angelzou",
"orange-ci": "loviselu,cristophwan",
"infra": "robinzhxie,loviselu"
}- Using
codeowners(CODEOWNERS format) to require owner approval based on changed files:
main:
pull_request:
- stages:
- name: Set Dynamic Codeowners
type: git:reviewer
options:
type: add-reviewer
# Parsed as CODEOWNERS unless the extension is .json
codeowners: .cnb/codeowners# Write general rules first, specific rules last
* @global-team
/src/frontend/ @frontend-owner
/src/frontend/auth.js @security-team- Using
codeowners(inline object), where thekeyis a CODEOWNERS pattern:
main:
pull_request:
- stages:
- name: Set Dynamic Codeowners
type: git:reviewer
options:
type: add-reviewer
codeowners:
"/src/frontend/": "name1,name2"
".cnb.yml": "name3"- Using
reviewersConfig(inline object) to match reviewers by changed files:
main:
pull_request:
- stages:
- name: Add Reviewers by Changed Files
type: git:reviewer
options:
type: add-reviewer
reviewersConfig:
"./src": "name1,name2"
".cnb.yml": "name3"- Using
reviewersandreviewersConfigtogether (union):
main:
pull_request:
- stages:
- name: Add Reviewers
type: git:reviewer
options:
type: add-reviewer
# Reviewers matched by changed files
reviewersConfig: reviewers-config.json
# Common reviewers, unioned with the above and randomly sampled (2)
reviewers: loviselu,robinzhxie,wenqiuli
count: 2- Selecting one reviewer from current repository members for review:
main:
pull_request:
- stages:
- name: Add Reviewer
type: git:reviewer
options:
type: add-reviewer-from-repo-membersBest Practices
Randomly Assign Reviewers and Notify
Randomly select N reviewers for a PR and send a notification to WeChat Enterprise:
main:
pull_request:
- stages:
- name: Add Reviewers
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}Auto-Merge after Approval and Notify
main:
review:
- stages:
- name: Auto-Merge after CR Approval
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: |
> Auto-Merge after CR Approval <@${CNB_BUILD_USER}>
> ${CNB_PULL_REQUEST_TITLE}
> [${CNB_EVENT_URL}](${CNB_EVENT_URL})
> ${REVIEWED_BY}