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

\==Updating PR Labels and Title==

* [Applicable Events](#git-pr-update-applicable-events)
* [How to Get PR ID](#git-pr-update-how-to-get-pr)
* [How to Include PR ID in Commit Logs](#git-pr-update-how-to-include-pr-id-in-commit-logs)
* [Parameters](#git-pr-update-parameters)
* [Output Results](#git-pr-update-output)
* [Permission Check](#git-pr-update-permission-check)
* [Configuration Examples](#git-pr-update-configuration-examples)

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

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

## How to Get PR ID {#git-pr-update-how-to-get-pr}

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

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

Parse the PR from the provided text file or text. `fromFile` takes precedence over `fromText`.

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

* **PR-related events:**

  Parse from the commit logs of the PR's commits. Additionally, include the current PR.

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

  Parse from the commit logs of the newly added commits.

* **Non-new branch `push` event:**

  Parse from the commit logs of the current push.

* **Other cases:**

  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 been deleted and cannot be retrieved from the context,
you must provide the content to parse using the `fromText` or `fromFile` parameters.
::::

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

* `PR-URL: <your-repo-slug>#<number>`
* `PR-URL: #<number>`

Where:

* `your-repo-slug` is the repository path, e.g., `cnbcool/cnb`.
* `number` is the PR number, found after the PR page URL.

> To distinguish from an `Issue`, the prefix `PR-URL:` is required.
> Note: Ensure there is a space before `#123` or `test/test#123`.

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

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

* [fromText](#git-pr-update-parameters-fromtext):
  Parse a PR from given text; defaults to parsing from commit history
* [fromFile](#git-pr-update-parameters-fromfile):
  Read content from a local file and parse the PR; takes precedence over `fromText`
* [label](#git-pr-update-parameters-label): Labels to add or remove
* [title](#git-pr-update-parameters-title): PR title
* [defaultColor](#git-pr-update-parameters-defaultcolor): Default color of labels being added

Detailed descriptions for each parameter are provided below.

### fromText {#git-pr-update-parameters-fromtext}

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

Parse the PR from the provided text.

If not declared, it will automatically parse from the commit logs in the context.
You can specify a text containing a `PR ID` reference to declare the target,
such as using it with a changelog generation plugin to automatically extract the `PR ID` from the changelog.

### fromFile {#git-pr-update-parameters-fromfile}

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

Read and parse the PR from a text file. Takes precedence over `fromText`.

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

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

Labels to be added or removed.

### title {#git-pr-update-parameters-title}

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

The title of the PR.

### defaultColor {#git-pr-update-parameters-defaultcolor}

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

The default color for the added label. This is only applicable when the `label.add` parameter is provided.

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

```javascript
{
    pullRequests // List of modified PRs
}
```

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

If the PRs to be updated belong to the pipeline's repository, and the current event is not an
[untrusted event](../../trigger-rule.md#untrusted-events),
the pipeline triggerer's permissions to modify the PR will not be checked.

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

The following pipeline implements the following functionalities:

1. **When the `pull_request` pipeline fails:** Add the label `To be modified`.
2. **When the `pull_request` pipeline succeeds:** Add the label `Pending review` and remove the label `To be modified`.
3. **When the `pull_request.merged` pipeline runs:**
   Add the label `To be released` and remove the label `Pending review`.

```yaml title=".cnb.yml"
main:
  pull_request:
    - stages:
        - name: check
          script: echo "do some check"
        - name: Add PR label - Pending review
          type: git:pr-update
          options:
            label:
              add:
                - Pending-review
              remove:
                - To-be-modified
      failStages:
        - name: Add PR label - To be modified
          type: git:pr-update
          options:
            label:
              add:
                - To-be-modified

  pull_request.merged:
    - stages:
        - name: check
          script: echo "do some check"
        - name: Add PR label - To be released
          type: git:pr-update
          options:
            label:
              add:
                - To-be-released
              remove:
                - Pending-review
```