git:pr-update

Updating PR Labels and Title; it can automatically locate the PR associated with the commit log.

When to use it: use it when labels should be applied to a PR automatically based on the pipeline result - for example adding a "ready for review" label after the pipeline passes, adding a "needs changes" label on failure, or updating the title/labels of PRs in bulk together with a changelog plugin. Such operations rely on locating the PR from the commit log, which is costly to script by hand, so git:pr-update folds this into a single built-in task.

• Applicable Events
• How to Get PR ID
• How to Include PR ID in Commit Logs
• Parameters
• Output Results
• Permission Check
• Configuration Examples

Applicable Events

All Events

How to Get PR ID

No extra configuration is needed by default: the task automatically determines which PR to operate on (see "Default Retrieval" below). Only configure fromText or 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.

Tips

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.

Tips

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

Parameters

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

• fromText: Parse a PR from given text; defaults to parsing from commit history
• fromFile: Read content from a local file and parse the PR; takes precedence over fromText
• label: Labels to add or remove
• title: PR title
• defaultColor: Default color of labels being added

Detailed descriptions for each parameter are provided below.

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

• type: String
• required: false

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

label

• type: UpdateLabel
• required: false

Labels to be added or removed.

title

• type: String
• required: false

The title of the PR.

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

{
    pullRequests // List of modified PRs
}

Permission Check

If the PRs to be updated belong to the pipeline's repository, and the current event is not an untrusted event, the pipeline triggerer's permissions to modify the PR will not be checked.

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.

.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