---
url: /en/build/internal-steps/git/auto-merge.md
---
`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).

The triggering conditions and timing of the `pull_request.mergeable` event can be found in the
[events](../../trigger-rule.md#pull_request-mergeable).

* [Applicable Events](#git-auto-merge-applicable-events)
* [Parameters](#git-auto-merge-parameters)
* [Output Results](#git-auto-merge-output)
* [Configuration Examples](#git-auto-merge-configuration-examples)
  * [Stand-alone Usage](#git-auto-merge-configuration-examples-standalone-usage)
  * [Used with Target Branch Push Event](#git-auto-merge-examples-push-event)
* [Best Practices](#git-auto-merge-best-practices)
  * [Using Squash Auto-Merge](#git-auto-merge-best-practices-using-squash-auto-merge)
  * [Automatically Selecting Merge Type](#git-auto-merge-best-practices-auto-select)
  * [Establishing Dedicated CR Group for Cross-Review
    Auto-Merge](#git-auto-merge-best-practices-dedicated-cr-group)

## Applicable Events {#git-auto-merge-applicable-events}

`pull_request.mergeable`

## Parameters {#git-auto-merge-parameters}

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

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

Detailed descriptions for each parameter are provided below.

### mergeType {#git-auto-merge-parameters-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 {#git-auto-merge-parameters-mergeCommitMessage}

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

Commit message for the merge.

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

2. 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:

```txt
chore: merge node(merged by CNB)

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

3. 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:

```yaml title=".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

```txt
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

```txt
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:

```txt
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
```

4. It can also be directly specified

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

```yaml title=".cnb.yml"
main:
  pull_request.mergeable:
    - stages:
        - name: automerge
          type: git:auto-merge
          options:
            mergeCommitMessage: $CNB_PULL_REQUEST_TITLE
```

### mergeCommitFooter {#git-auto-merge-parameters-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:

```yaml title=".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"
```

```txt
add feature for some jobs

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

### removeSourceBranch {#git-auto-merge-parameters-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 {#git-auto-merge-parameters-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 {#git-auto-merge-parameters-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 {#git-auto-merge-output}

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

## Configuration Examples {#git-auto-merge-configuration-examples}

### Stand-alone Usage {#git-auto-merge-configuration-examples-standalone-usage}

```yaml title=".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 {#git-auto-merge-examples-push-event}

```yaml title=".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 {#git-auto-merge-best-practices}

### Using `squash` Auto-Merge {#git-auto-merge-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.

```yaml title=".cnb.yml"
main:
  review:
    - stages:
        - name: automerge
          type: git:auto-merge
          options:
            mergeType: squash
            removeSourceBranch: true
```

### Automatically Selecting Merge Type with `auto` {#git-auto-merge-best-practices-auto-select}

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

```yaml title=".cnb.yml"
main:
  review:
    - stages:
        - name: automerge
          type: git:auto-merge
          options:
            mergeType: auto
```

### Establishing a Dedicated CR Group for Cross-Review Auto-Merge {#git-auto-merge-best-practices-dedicated-cr-group}

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

**Auto-merge after review approval and notify:**

```yaml title=".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:**

```yaml title=".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}
```