---
url: /en/build/internal-steps/tapd/status-update.md
description: >
  Updates the status of TAPD linked items (story, task, or bug), for letting
  TAPD item status follow code progress, such as marking an item done after a PR
  is merged.
---
`tapd:status-update`

**Update the status of TAPD-associated items (story, task, or bug)**

When submitting code, you can add TAPD source code keywords in the **commit message** or **PR description**.
The cloud-native build system will automatically recognize and associate commits, PRs, and TAPD work items.

**When to use it**: use it when the status of TAPD work items should follow progress in code - for
example setting the associated story/task/bug to "done" automatically once the PR is merged,
instead of changing each status by hand in TAPD. Scripting this means calling the TAPD API and
matching associated items yourself, so `tapd:status-update` folds it into a single built-in task.

In pipelines triggered by code pushes, PRs, and tags,
you can update the information of TAPD-associated items through this task.

**Prerequisites**

* The TAPD feature must be enabled in the root organization.
* The pipeline triggerer must have a bound TAPD account.

**TAPD Association Item Filtering Rules**

The pipeline will filter associated TAPD work items based on the following rules:

**1. When the `fromFile` or `fromText` parameters are provided:**

Parse the commit IDs from the provided text file or text, and query the associated TAPD work items.

The `fromFile` parameter takes precedence over `fromText`.

**2. When neither the `fromFile` nor `fromText` parameters are provided:**

* **PR-related events:**

  Query the TAPD work items associated with the commits and PR description of the PR.

* **`commit.add` event:**

  Query the TAPD work items associated with the newly added commits.

* **`push` event for non-new branches:**

  Retrieve the associated TAPD work items from the commit logs of all commits in this push.

* **Other cases:**

  Query the TAPD work items associated with the latest commit.

**TAPD Association Item Types**

The type in the TAPD work item `source code keyword` is the work item type, such as: story, task, bug.

::: tip
The source code keyword for TAPD tasks may be either story or task. Please distinguish carefully.
:::

* [Applicable Events](#tapd-status-update-applicable-events)
* [Parameters](#tapd-status-update-parameters)
* [Configuration Examples](#tapd-status-update-configuration-examples)

## Applicable Events {#tapd-status-update-applicable-events}

[All Events](../../trigger-rule.md#trigger-event)

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

The list below gives an overview of all `tapd:status-update` parameters.

* [status](#tapd-status-update-parameters-status): Target status
* [when](#tapd-status-update-parameters-when): Update only items in a given status
* [type](#tapd-status-update-parameters-type): Update only items of a given type (story/task/bug)
* [fromText](#tapd-status-update-parameters-from-text): Parse commit ids from text to find linked items
* [fromFile](#tapd-status-update-parameters-from-file): Parse commit ids from a file to find linked items

Detailed descriptions for each parameter are provided below.

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

* Type: `String`
* Required: `true`

Target status.

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

* Type: `String` | `Array<String>`
* Required: `false`

Update work items with the specified status. No filtering is applied if left empty.

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

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

Update work items of the specified type. No filtering is applied if left empty.

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

* Type: `String`
* Required: `false`

Parse commit IDs (up to 50) from the provided text and query their associated work items.

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

* Type: `String`
* Required: `false`

Parse commit IDs from the provided text file and query their associated work items.

## Configuration Examples {#tapd-status-update-configuration-examples}

1. Update the status of all TAPD-associated items:

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

2. Update the status of TAPD-associated items that meet specific conditions:

```yaml title=".cnb.yml"  
main:
  pull_request.merged:
    - stages:
        - name: update tapd status
          type: tapd:status-update
          options:
            status: Completed
            when:
              - developing
            type: story
```

3. Parse commit IDs from `fromText`, query TAPD-associated items, and update their status:

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