---
url: /zh/build/internal-steps/tapd/status-update.md
---
`tapd:status-update`

\==更新 tapd 关联项（story、task 或 bug）状态==

在代码提交时，您可以在**提交信息**或**PR 描述**中添加 TAPD 源码关键字，
云原生构建系统将自动识别并关联 Commits、PR 和 TAPD 工作项。

在代码推送、PR 和 Tag 相关流水线中，可以通过该任务更新 TAPD 关联项的信息。

**前提条件**

* 需在根组织中启用 TAPD 功能。
* 流水线触发者需绑定 TAPD 账号。

**TAPD 关联项筛选规则**

流水线将根据以下规则筛选关联的 TAPD 工作项：

**1. 当传入 `fromFile` 或 `fromText` 参数时：**

从传入的文本文件或文本中解析出 commit IDs，并查询其关联的 TAPD 工作项。

`fromFile` 优先级高于 `fromText`。

**2. 当未传入 `fromFile` 或 `fromText` 参数时：**

* **PR 相关事件：**

  查询该 PR 的 commits 以及 PR 描述中关联的 TAPD 工作项。

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

  查询新增 commits 关联的 TAPD 工作项。

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

  从本次推送的所有 commits 的提交日志中获取关联的 TAPD 工作项。

* **其他情况：**

  查询最新 commit 所关联的 TAPD 工作项。

**TAPD 关联项类型**

TAPD 工作项 `源码关键字` 中的类型即为工作项类型，如：story、task、bug。

> 需要注意的是，TAPD 任务的源码关键字可能为 story 或 task，请注意区分。

* [适用事件](#tapd-status-update-applicable-events)
* [参数](#tapd-status-update-parameters)
* [配置样例](#tapd-status-update-configuration-examples)

## 适用事件 {#tapd-status-update-applicable-events}

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

## 参数 {#tapd-status-update-parameters}

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

* [status](#tapd-status-update-parameters-status)：目标状态
* [when](#tapd-status-update-parameters-when)：仅更新指定状态的工作项
* [type](#tapd-status-update-parameters-type)：仅更新指定类型（story/task/bug）的工作项
* [fromText](#tapd-status-update-parameters-from-text)：从文本解析 commit id，查询关联工作项
* [fromFile](#tapd-status-update-parameters-from-file)：从文件解析 commit id，查询关联工作项

各参数详细说明如下。

### status {#tapd-status-update-parameters-status}

* type: `String`
* required: `true`

目标状态。

### when {#tapd-status-update-parameters-when}

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

更新指定状态的工作项，为空时不做过滤。

### type {#tapd-status-update-parameters-type}

* `Enum<String>`: story | task | bug
* required: `false`

更新指定类型的工作项，为空时不做过滤。

### fromText {#tapd-status-update-parameters-from-text}

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

从文本中解析出 commit id，查询其关联的工作项。

### fromFile {#tapd-status-update-parameters-from-file}

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

从文本文件中解析出 commit id，查询其关联的工作项。

## 配置样例 {#tapd-status-update-configuration-examples}

1. 更新所有 TAPD 关联项的状态

```yaml title=".cnb.yml"
main:
  push:
    - stages:
        - name: update tapd status
          type: tapd:status-update
          options:
            status: 进行中
```

2. 对符合条件的 TAPD 关联项更新状态

```yaml title=".cnb.yml"
main:
  pull_request.merged:
    - stages:
        - name: update tapd status
          type: tapd:status-update
          options:
            status: 已完成
            when:
              - 进行中
            type: story
```

3. 从 `fromText` 中解析 commit id，查询 TAPD 关联项并更新状态

```yaml title=".cnb.yml"
$:
  tag_push:
    - stages:
        - name: 生成 changelog
          image: cnbcool/changelog
          settings:
            dryRun: true
            linkReferences: false
          exports:
            latestChangeLog: RELEASE_NOTES
        - name: tapd
          type: tapd:status-update
          options:
            status: 已发布
            type: story
            fromText: $RELEASE_NOTES
```