tapd:status-update

911 字约 3 分钟

tapd:status-update

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

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

使用场景：想让 TAPD 工作项状态跟随代码进展自动流转时使用——例如 PR 合并后把关联的 story / task / bug 自动置为「已完成」，无需人工回到 TAPD 逐个改状态。写脚本需要自行对接 TAPD 接口、匹配关联项，tapd:status-update 把这一步收敛成一个内置任务。

在代码推送、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 的全部参数。

status：目标状态
when：仅更新指定状态的工作项
type：仅更新指定类型（story/task/bug）的工作项
fromText：从文本解析 commit id，查询关联工作项
fromFile：从文件解析 commit id，查询关联工作项

各参数详细说明如下。

status

type: String
required: true

目标状态。

when

type: String | Array<String>
required: false

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

type

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

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

fromText

type: String
required: false

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

fromFile

type: String
required: false

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

配置样例

更新所有 TAPD 关联项的状态

.cnb.yml
main:
  push:
    - stages:
        - name: update tapd status
          type: tapd:status-update
          options:
            status: 进行中

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

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

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

.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