---
url: /en/build/internal-steps/git/issue-update.md
description: >
  Updates Issue status and labels, for letting issues change state with code
  progress, such as closing an issue on commit or labeling by pipeline result.
---
`git:issue-update`

**Update Issue Status**, close or open an issue, and modify issue labels.

**When to use it**: use it when an issue's status should follow progress in code - for example
closing an issue automatically when a commit references it, or labelling an issue as "needs
changes" when its pipeline fails. Such operations rely on locating the issue from the commit log,
which is costly to script by hand, so `git:issue-update` folds this into a single built-in task.

* [Applicable Events](#git-issue-update-applicable-events)
* [Work Mechanism](#git-issue-update-work-mechanism)
* [How to Get Issue](#git-issue-update-how-to-get-issue)
* [Including Issue in Commit Logs](#git-issue-update-how-to-include-issue-in-commit-logs)
* [Parameters](#git-issue-update-parameters)
* [Output Results](#git-issue-update-output)
* [Permission Check](#git-issue-update-permission-check)
* [Configuration Examples](#git-issue-update-configuration-examples)

## Applicable Events {#git-issue-update-applicable-events}

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

## Work Mechanism {#git-issue-update-work-mechanism}

Check if the issue exists -> Check if it meets the `when` condition (optional) ->
Check if it meets the `lint` condition (optional) -> Update issue status or labels

## Issue Retrieval Method {#git-issue-update-how-to-get-issue}

No extra configuration is needed by default: the task automatically determines which Issue
to operate on (see "Default Retrieval" below). Only configure
[fromText](#git-issue-update-parameters-fromText) or
[fromFile](#git-issue-update-parameters-fromFile) when you want to parse the `IssueId`
from custom text instead of commit logs; see the "Parameters" section for details.

**1. When `fromFile` or `fromText` is configured:**

Retrieve and parse from the provided text file or text. `fromFile` takes precedence over `fromText`.

**2. Default Retrieval (when neither `fromFile` nor `fromText` is configured):**

* **Issue-related events:**

  Retrieve the current Issue.

* **PR-related events:**

  Retrieve and parse from the commit logs of the PR's commits.

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

  Retrieve and parse from the commit logs of the newly added commits.

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

  Retrieve and parse from the commit logs of the pushed commits.

* **Other cases:**

  Retrieve and parse from the commit log of the latest commit.

::::tip
If you need to use this in a `branch.delete` event,
since the branch has already been deleted and cannot be retrieved from the context,
you must provide the parsing content using the `fromText` or `fromFile` parameter.
::::

**Parsing format:** From the source text above, extract the `IssueId` in the following two formats:

* `#IssueID`: Represents an Issue in the current repository. For example,
  `#123` refers to Issue ID 123 in the current repository.
* `groupName/repoName#IssueID`: Represents a cross-repository (other repository) Issue. For example,
  `test/test#123` refers to Issue ID 123 in the `test/test` repository.

::: tip
`#123` or `test/test#123` must be preceded by a space.
:::

## Including Issue in Commit Logs {#git-issue-update-how-to-include-issue-in-commit-logs}

When committing code, you can include the associated `IssueID` in the commit log,
which can be automatically extracted when using the current built-in task to update the associated issue for updating
labels and status.

It is recommended to include the `IssueID` in the body of the commit log. Here are two command-line methods:

* Method 1: Use `shift + enter` for a new line, and it's recommended to add a blank line between the title and body.

```shell
git commit -m "fix(Cloud-Native Build): Fix an error

cnb/feedback#123"
```

* Method 2: Using this method will create two new lines between the title and body.

```shell
git commit -m "fix(Cloud-Native Build): Fix an error" -m "cnb/feedback#123"
```

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

The list below gives an overview of all `git:issue-update` parameters.

* [fromText](#git-issue-update-parameters-fromText):
  Parse an IssueId from given text; defaults to parsing from commit history
* [fromFile](#git-issue-update-parameters-fromFile):
  Read and parse an IssueId from a local file; takes precedence over `fromText`
* [state](#git-issue-update-parameters-state): Close or open the issue
* [label](#git-issue-update-parameters-label): Add/remove issue labels
* [assignee](#git-issue-update-parameters-assignee): Add/remove assignees
* [when](#git-issue-update-parameters-when): Filter condition; operate only when satisfied
* [lint](#git-issue-update-parameters-lint): Check condition; raise an error when not satisfied
* [defaultColor](#git-issue-update-parameters-defaultColor): Default color of labels being added
* [prefix](#git-issue-update-parameters-prefix): Issue prefixes to handle

Detailed descriptions for each parameter are provided below.

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

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

Parses `IssueId` from the provided text.

If not specified, it automatically parses from the commit records in the context.
You can specify a text containing `IssueId` references to declare the target,
such as when used in conjunction with a changelog generation plugin to automatically extract `IssueId` from the
changelog.

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

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

Reads content from a text file and parses `IssueId`. This takes precedence over `fromText`.

**When the content is too large,
it is recommended to use this parameter to pass the content via a file to avoid exceeding limits.**

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

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

Corresponds to the `state` attribute. When set to `close`, it can close the `Issue`.

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

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

Description of the operation on labels.

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

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

Description of operations for the `assignee`.

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

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

Filter conditions, where multiple conditions are connected by `or`. When empty, it indicates operations on all `Issues`.

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

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

Check if the `Issue` meets the conditions. If not met, an exception is thrown.
Multiple conditions are connected by `or`, and when empty, no checks are performed.

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

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

Default color for added labels, effective only when the `label.add` parameter is provided.

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

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

The issue prefixes that need to be processed, for example, if `close` and `closed` is passed,
it will handle all issues prefixed with `close` and `closed`. For instance, `close #123` or `closed #123 #456`.

### Type Definitions {#git-issue-update-parameters-type-definitions}

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

* `Enum<String>`: open | close

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

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

List of labels to add. If the label does not exist, it will be automatically created.

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

List of labels to remove.

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

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

List of assignees to add.

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

List of assignees to remove.

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

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

Labels, where multiple values are connected by `or`.

## Output Results {#git-issue-update-output}

```javascript
{
    issues // List of issues
}
```

## Permission Check {#git-issue-update-permission-check}

If the issue that needs to be updated belongs to the repository to which the pipeline belongs,
and the current event is not an [untrusted event](../../trigger-rule.md#untrusted-events),
then the permission of the pipeline triggerer to modify the issue will not be checked.

## Configuration Examples {#git-issue-update-configuration-examples}

* After merging into main, update labels

```yaml title=".cnb.yml"
main:
  push:
    - stages:
        - name: update issue
          type: git:issue-update
          options:
            # Remove the "In Progress" label and add the "Pre-release" label
            label:
              add: Pre-release
              remove: In Progress
            # Perform the above label operations only when there are "feature" or "bug" labels
            when:
              label:
                - feature
                - bug
```

* When a tag is pushed, close the issue and update labels

```yaml title=".cnb.yml"
$:
  tag_push:
    - stages:
        - name: release operation
          script: echo "Use release tasks instead of the current task"
        # Perform issue update operation after release operation
        - name: update issue
          type: git:issue-update
          options:
            # Close the issue
            state: close
            # You can specify prefixes for issues that need to be closed.
            # If set, only those containing "close #123" or
            # "closed #123" will be closed.
            # prefix:
            #   - close
            #   - closed
            # Remove the "Pre-release" label and add the "Released" label
            label:
              add: Released
              remove: Pre-release
            # Perform the above operations only when there are "feature" or "bug" labels
            when:
              label:
                - feature
                - bug
```

* When tag is pushed, find `IssueId` included in the changes
  between the current tag and the previous tag, and add labels

```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: Requirement Accepted
            when:
              label: feature
```