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

\==更新 Issue 状态==，关闭或打开 Issue，修改 Issue 标签。

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

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

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

## 工作机制 {#git-issue-update-work-mechanism}

查找 Issue 是否存在 -> 检查是否符合 when 条件（可选）
-> 检查是否符合 lint 条件（可选）-> 更新 issue 状态或标签

## Issue 获取方式 {#git-issue-update-how-to-get-issue}

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

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

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

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

* **Issue 相关事件：**

  取当前 Issue。

* **PR 相关事件：**

  从该 PR 的 commits 的提交日志中解析获取。

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

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

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

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

* **其他情况：**

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

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

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

* `#IssueID`：表示当前仓库的 Issue。例如 `#123`，表示当前仓库 id 为 123 的 Issue。
* `groupName/repoName#IssueID`：表示跨仓库（其他仓库）的 Issue。
  例如 `test/test#123`，表示 test/test 仓库中 id 为 123 的 Issue。

> 注意：`#123` 或 `test/test#123` 前需要有空格。

## 提交日志中如何带上 `IssueID` {#git-issue-update-how-to-include-issue-id-in-commit-logs}

提交代码时，可在提交日志中加上关联的 `IssueID`，
使用该内置任务时，可自动提取到关联 Issue，
用于更新 Issue 标签和状态

推荐在提交日志的 body 中带上 `IssueID`，命令行操作方式如下：

* 方法一：用 `shift + enter` 换行，建议 title 和 body 之间加上一个空行

```shell
git commit -m "fix(云原生构建): 修复一个错误

cnb/feedback#123"
```

* 方法二：

以下提交方式，title 和 body 之间会产生两个换行

```shell
git commit -m "fix(云原生构建): 修复一个错误" -m "cnb/feedback#123"
```

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

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

* [fromText](#git-issue-update-parameters-fromText)：从给定文本解析 IssueId，缺省时从提交记录解析
* [fromFile](#git-issue-update-parameters-fromFile)：从本地文件读取并解析 IssueId，优先级高于 `fromText`
* [state](#git-issue-update-parameters-state)：关闭或打开 Issue
* [label](#git-issue-update-parameters-label)：添加/移除 Issue 标签
* [assignee](#git-issue-update-parameters-assignee)：添加/移除处理人
* [when](#git-issue-update-parameters-when)：过滤条件，满足才操作
* [lint](#git-issue-update-parameters-lint)：检查条件，不满足则抛异常
* [defaultColor](#git-issue-update-parameters-defaultColor)：添加标签的默认颜色
* [prefix](#git-issue-update-parameters-prefix)：需要处理的 Issue 前缀

各参数详细说明如下。

### fromText {#git-issue-update-parameters-fromText}

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

从给定的文本中解析 `IssueId`。

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

### fromFile {#git-issue-update-parameters-fromFile}

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

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

**当内容过多时，建议使用该参数，将内容通过文件传递，避免超出限制。**

### state {#git-issue-update-parameters-state}

* type: [IssueStateMap](#git-issue-update-parameters-type-definitions-issuestatemap)
* required: `false`

对应 `state` 属性，为 `close` 时，可关闭 `Issue`。

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

* type: [UpdateLabel](#git-parameters-type-definitions-updatelabel)
* required: `false`

对 `label` 的操作描述。

### assignee {#git-issue-update-parameters-assignee}

* type: [UpdateAssignee](#git-parameters-type-definitions-updateassignee)
* required: `false`

对 `处理人` 的操作描述。

### when {#git-issue-update-parameters-when}

* type: [IssueUpdateStatus](#git-issue-update-parameters-type-definitions-issueupdatestatus)
* required: `false`

过滤条件，多个条件之间是 `or` 关系。为空时表示对所有 `Issue` 操作。

### lint {#git-issue-update-parameters-lint}

* type: [IssueUpdateStatus](#git-issue-update-parameters-type-definitions-issueupdatestatus)
* required: `false`

检查 `Issue` 是否满足条件，不满足时抛出异常，
多个条件之间是 `or` 关系，为空时表示不做检查。

### defaultColor {#git-issue-update-parameters-defaultColor}

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

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

### prefix {#git-issue-update-parameters-prefix}

* type: `String[]`
* required: `false`

需要处理的 issue 前缀，例如如果传入的是 `close` 和 `closed`，
则会处理所有带有 `close` 和 `closed` 前缀的 issue。
例如 `close #123` 或 `closed #123 #456`

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

#### IssueStateMap {#git-issue-update-parameters-type-definitions-issuestatemap}

* `Enum<String>`:  open | close

#### UpdateLabel {#git-parameters-type-definitions-updatelabel}

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

要添加的标签列表，标签不存在时，会自动创建。

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

要移除的标签列表

#### UpdateAssignee {#git-parameters-type-definitions-updateassignee}

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

要添加的处理人列表。

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

要移除的处理人列表

#### IssueUpdateStatus {#git-issue-update-parameters-type-definitions-issueupdatestatus}

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

标签，多个值之间是 `or` 关系

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

```javascript
{
    issues // issue 列表
}
```

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

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

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

* 合并到 main 后，更新标签

```yaml title=".cnb.yml"
main:
  push:
    - stages:
        - name: update issue
          type: git:issue-update
          options:
            # 移除 “开发中” 标签，添加 “预发布” 标签
            label:
              add: 预发布
              remove: 开发中
            # 当有 “feature” 或 “bug” 标签才进行上述标签操作
            when:
              label:
                - feature
                - bug
```

* Tag push 时，关闭 Issue，更新标签

```yaml title=".cnb.yml"
$:
  tag_push:
    - stages:
        - name: 发布操作
          script: echo "可用发布任务替代当前任务"
        # 发布操作后执行 issue 更新操作
        - name: update issue
          type: git:issue-update
          options:
            # 关闭 issue
            state: close
            # 可选择指定需要关闭的 issue 前缀，
            # 如果设置了，则包含 close #123 或
            # closed #123 这种才会被关闭
            # prefix:
            #   - close
            #   - closed
            # 移除 “预发布” 标签，添加 “已发布” 标签
            label:
              add: 已发布
              remove: 预发布
            # 当有 “feature” 或 “bug” 标签才进行上述操作
            when:
              label:
                - feature
                - bug
```

* Tag push 时，根据当前 tag 和前一个 tag 的变更内容，
  找到变更内容中包含的 `IssueId`，并添加标签

```yaml title=".cnb.yml"
$:
  tag_push:
    - stages:
        - name: changelog
          image: cnbcool/changelog
          settings:
            latestChangeLogTarget: LATEST_CHANGELOG.md
        - name: update issue
          type: git:issue-update
          options:
            fromFile: LATEST_CHANGELOG.md
            label:
              add: 需求已接收
            when:
              label: feature
```