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

\==更新 PR 的标签、标题==。

* [适用事件](#git-pr-update-applicable-events)
* [PR ID 获取方式](#git-pr-update-how-to-get-pr)
* [提交日志中如何带上 PR ID](#git-pr-update-how-to-include-pr-id-in-commit-logs)
* [参数](#git-pr-update-parameters)
* [输出结果](#git-pr-update-output)
* [权限检查](#git-pr-update-permission-check)
* [配置样例](#git-pr-update-configuration-examples)

## 适用事件 {#git-pr-update-applicable-events}

[所有事件](../../trigger-rule.md#trigger-event)

## PR 获取方式 {#git-pr-update-how-to-get-pr}

默认情况下无需额外配置：任务会自动判断要操作的 PR（见下文的「默认获取」）。
只有当你想从某段自定义文本中解析 PR（而非使用提交记录）时，
才需要配置 [fromText](#git-pr-update-parameters-fromtext) 或
[fromFile](#git-pr-update-parameters-fromfile)，详细说明见「参数」章节。

**1. 配置了 `fromFile` 或 `fromText` 时：**

从传入的文本文件或文本中解析获取。`fromFile` 优先级高于 `fromText`。

**2. 默认获取（未配置 `fromFile` 或 `fromText` 时）：**

* **PR 相关事件：**

  从该 PR 的 commits 的提交日志中解析获取。同时追加当前 PR。

* **`commit.add` 事件：**

  从新增 commits 的提交日志中解析获取。

* **非新建分支的 `push` 事件：**

  从本次推送 commits 的提交日志中解析获取。

* **其他情况：**

  从最新 commit 的提交日志中解析获取。

::::tip
如需在 `branch.delete` 事件中使用，由于分支已删除、
无法从上下文获取，需通过 `fromText` 或 `fromFile` 参数提供解析内容。
::::

\*\*解析格式：\*\*从上述来源的文本中，提取以下两种格式的 PR：

* `PR-URL: <your-repo-slug>#<number>`
* `PR-URL: #<number>`

`your-repo-slug` 为仓库的路径，比如 `cnbcool/cnb`；
`number` 为 PR 的编号，为 PR 页面地址后的数字。

> 为了和 `Issue` 区分，需要在前面加上 `PR-URL:`。
> 注意：`#123` 或 `test/test#123` 前需要有空格。

## 参数 {#git-pr-update-parameters}

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

* [fromText](#git-pr-update-parameters-fromtext)：从给定文本中解析 PR，缺省时自动从提交记录解析
* [fromFile](#git-pr-update-parameters-fromfile)：从本地文件读取内容并解析 PR，优先级高于 `fromText`
* [label](#git-pr-update-parameters-label)：要添加或删除的标签
* [title](#git-pr-update-parameters-title)：PR 标题
* [defaultColor](#git-pr-update-parameters-defaultcolor)：添加标签的默认颜色

各参数详细说明如下。

### fromText {#git-pr-update-parameters-fromtext}

* type: `String`
* required: `false`

从给定的文本中解析 PR。

不声明时，自动从上下文里的提交记录解析。
可以指定一个包含 `PR ID` 引用的文本来声明操作对象，
比如配合变更日志生成插件一起使用，将变更日志中的 `PR ID` 自动提取出来。

### fromFile {#git-pr-update-parameters-fromfile}

* type: `String`
* required: `false`

从文本文件中读取内容并解析 PR。优先级高于 `fromText`。

### label {#git-pr-update-parameters-label}

* type: [UpdateLabel](./issue-update.md#git-parameters-type-definitions-updatelabel)
* required: `false`

需要添加、删除的标签。

### title {#git-pr-update-parameters-title}

* type: `String`
* required: `false`

PR 的标题。

### defaultColor {#git-pr-update-parameters-defaultcolor}

* type: `String`
* required: `false`

添加的标签的默认颜色，当有传入 `label.add` 参数时才有效。

## 输出结果 {#git-pr-update-output}

```javascript
{
    pullRequests // 修改的 pr 列表
}
```

## 权限检查  {#git-pr-update-permission-check}

若需要更新的 PR 属于流水线所属仓库，
且当前事件不属于[不可信事件](../../trigger-rule.md#untrusted-events)，
则不会检查流水线触发者是否拥有修改 PR 的权限。

## 配置样例 {#git-pr-update-configuration-examples}

如下流水线实现了以下功能：

1. `pull_request` 流水线失败，增加标签 `待修改`。
2. `pull_request` 流水线成功，增加标签 `待评审`，删除标签 `待修改`。
3. `pull_request.merged` 流水线，增加标签 `待发布`，删除标签 `待评审`。

```yaml title=".cnb.yml"
main:
  pull_request:
    - stages:
        - name: check
          script: echo "do some check"
        - name: 添加PR标签-待评审
          type: git:pr-update
          options:
            label:
              add:
                - 待评审
              remove:
                - 待修改
      failStages:
        - name: 添加PR标签-待修改
          type: git:pr-update
          options:
            label:
              add:
                - 待修改

  pull_request.merged:
    - stages:
        - name: check
          script: echo "do some check"
        - name: 添加PR标签-待发布
          type: git:pr-update
          options:
            label:
              add:
                - 待发布
              remove:
                - 待评审
```