git:auto-merge

About 1418 wordsAbout 5 min

git:auto-merge

Automatically merges a Pull Request, typically used after the pull_request pipeline checks and code review, in the pull_request.mergeable pipeline to automatically merge the PR without manual intervention.

Terminology: reviewer is the person who reviews the PR, while assignee is the person assigned to handle the PR (shown as the assignee on the PR page).

When to use it: use it when a PR should be merged automatically once checks pass and reviews are approved - for example when the repository rule is "auto-merge as soon as the pipeline passes and a reviewer approves", with no manual click on the merge button. Scripting this means requesting a token and evaluating the merge conditions yourself, so git:auto-merge folds it into a single built-in task.

The triggering conditions and timing of the pull_request.mergeable event can be found in the events.

Applicable Events
Parameters
Output Results
Configuration Examples
- Stand-alone Usage
- Used with Target Branch Push Event
Best Practices

Applicable Events

pull_request.mergeable

Parameters

The list below gives an overview of all git:auto-merge parameters.

mergeType: Merge strategy
mergeCommitMessage: Commit message of the merge commit
mergeCommitFooter: Footer of the merge commit, separated by \n
removeSourceBranch: Whether to delete the source branch after merging
ignoreAssignee: Whether to ignore the assignee and force the merge
allowAssigneeApprovedMerge: Whether to auto-merge when an assignee has approved

Detailed descriptions for each parameter are provided below.

mergeType

type: merge | squash | rebase | auto
required: false
default: auto

Merge strategy, defaulting to auto: merges by merge if multiple people contribute, otherwise uses squash.

mergeCommitMessage

type: String
required: false

Commit message for the merge.

When the merge strategy is rebase, this information is not required.
When the merge strategy is merge, the default message is chore: merge node(merged by CNB), automatically appending PR references, reviewers' names, and contributors' names. For example:

chore: merge node(merged by CNB)

PR-URL: !916
Reviewed-By: tom
Reviewed-By: jerry
Co-authored-by: jack

When the merge strategy is squash, the default value is the first commit message of the PR. It also appends PR references, reviewers' names, and contributors' names. For example:

.cnb.yml
main:
  pull_request.mergeable:
    - stages:
        - name: automerge
          type: git:auto-merge
          options:
            mergeType: squash

This configuration will result in the following effect:

Suppose a PR (feat/model-a -> main) has two commit records:

Commit 1: Submitted on October 1, 2023

feat(model-a): Add a new feature to module A

Due to some reason, add a certain feature

close #10

Commit 2: Fixed some issues pointed out during code review, submitted on October 2, 2023

fix(model-a): Fix issues pointed out during review

After automatic merging, a commit node like this will appear on the main branch, where the subsequent commit record (Commit 2) will be erased:

feat(model-a): Add a new feature to module A

Due to some reason, add a certain feature

close #10

PR-URL: !3976
Reviewed-By: tom
Reviewed-By: jerry
Co-authored-by: jack

It can also be directly specified

For example, specifying it as the title of the current PR through an environment variable:

.cnb.yml
main:
  pull_request.mergeable:
    - stages:
        - name: automerge
          type: git:auto-merge
          options:
            mergeCommitMessage: $CNB_PULL_REQUEST_TITLE

mergeCommitFooter

type: String
required: false

Footer information to be set for the merge, with multiple footers separated by \n, effective only for merge and squash.

When the merge strategy is rebase, this information is not required.

When the merge strategy is merge or squash, the provided information will be added as footers line by line, followed by PR references, reviewers' names, and contributors' names. For example:

.cnb.yml
main:
  pull_request.mergeable:
    - stages:
        - name: automerge
          type: git:auto-merge
          options:
            mergeType: squash
            mergeCommitMessage: "add feature for some jobs"
            mergeCommitFooter: "--story=123\n--story=456"

add feature for some jobs

--story=123
--story=456
PR-URL: #916
Reviewed-By: tom
Reviewed-By: jerry
Co-authored-by: jack

removeSourceBranch

type: Boolean
required: false
default: false

Whether to delete the source branch after merging.

This value is irrelevant when the source branch and target branch are in different repositories.

ignoreAssignee

type: Boolean
required: false
default: false

Whether to ignore the assignee.

When a PR has a specified assignee, this task will not automatically merge the PR because the assignee is meant to assign someone to handle it manually.

Setting this to true allows for forcibly merging the PR even if there is an assignee.

allowAssigneeApprovedMerge

type: Boolean
required: false
default: false

Whether to allow automatic merging when a PR assignee has approved the PR.

When set to true, and the current PR reviewers include an assignee whose state is approved, automatic merging proceeds with the same behavior as ignoreAssignee: true.

If the PR has multiple assignees, approval from any one assignee is enough to allow automatic merging.

Output Results

{
    reviewedBy, // String, information of the contributor appended to the commit message
    reviewers, // Array<String>, list of reviewers
}

Configuration Examples

Stand-alone Usage

.cnb.yml
main:
  pull_request.mergeable:
    - stages:
        - name: automerge
          type: git:auto-merge
          options:
            mergeType: merge

When a PR on the main branch triggers the pull_request.mergeable event, the PR will be automatically merged using the merge strategy.

Used with Target Branch `push` Event

.cnb.yml
main:
  push:
    - stages:
        - name: build
          script: npm run build
        - name: publish
          script: npm run publish
  pull_request.mergeable:
    - stages:
        - name: automerge
          type: git:auto-merge
          options:
            mergeType: merge

When a PR on the main branch triggers the pull_request.mergeable event, the PR will be automatically merged using the merge method.

After the merge, the last reviewer who approved the review will act as the trigger, initiating the push event on the target branch (main), and the declared build and publish processes will continue to execute.

Best Practices

Using `squash` Auto-Merge

Utilize squash merging to create only one commit node on the target branch for each PR and optionally delete the source branch if permissions allow.

.cnb.yml
main:
  review:
    - stages:
        - name: automerge
          type: git:auto-merge
          options:
            mergeType: squash
            removeSourceBranch: true

Automatically Selecting Merge Type with `auto`

Automatically determine the merge type based on whether multiple people are contributing (use merge) or if it's a single contributor (use squash).

.cnb.yml
main:
  review:
    - stages:
        - name: automerge
          type: git:auto-merge
          options:
            mergeType: auto

Establishing a Dedicated CR Group for Cross-Review Auto-Merge

Automatically merge after code review approval, recording the reviewer in the commit message.
Notify reviewers when a PR is created or updated.

Auto-merge after review approval and notify:

.cnb.yml
main:
  pull_request.mergeable:
    - stages:
        - name: Auto-Merge after CR Approval
          type: git:auto-merge
          options:
            mergeType: squash
            mergeCommitMessage: $CNB_LATEST_COMMIT_MESSAGE
          exports:
            reviewedBy: REVIEWED_BY
        - name: notify
          image: tencentcom/wecom-message
          settings:
            robot: "your-robot-key"
            msgType: markdown
            content: |
              > Auto-Merge after CR Approval <@${CNB_BUILD_USER}>
              >
              > ${CNB_PULL_REQUEST_TITLE}
              > [${CNB_EVENT_URL}](${CNB_EVENT_URL})
              >
              > ${REVIEWED_BY}

Notify reviewers when a PR is created or updated:

.cnb.yml
main:
  pull_request:
    - stages:
        # ...other tasks omitted
        - name: notify
          image: tencentcom/wecom-message
          settings:
            robot: "your-robot-key"
            msgType: markdown
            content: |
              > ${CURR_REVIEWER_FOR_AT}
              >
              > ${CNB_PULL_REQUEST_TITLE}
              > [${CNB_EVENT_URL}](${CNB_EVENT_URL})
              >
              > from ${CNB_BUILD_USER}