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

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

* [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.

> Note: `#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
```