---
url: /zh/build/internal-steps/git/auto-merge.md
---
`git:auto-merge`

\==自动合并 Pull Request==，一般用于 PR 通过 `pull_request` 流水线检查
和 Code Review 后，在 `pull_request.mergeable` 流水线中自动合并 PR，无需手动点击合并按钮。

术语约定：`reviewer`（评审人）指评审该 PR 的人，`assignee`（处理人，即 PR
界面里的「指派人」）指被指派处理该 PR 的人。

`pull_request.mergeable` 事件触发条件和时机参考 [事件](../../trigger-rule.md#pull_request-mergeable)。

* [适用事件](#git-auto-merge-applicable-events)
* [参数](#git-auto-merge-parameters)
* [输出结果](#git-auto-merge-output)
* [配置样例](#git-auto-merge-configuration-examples)
  * [单独使用](#git-auto-merge-configuration-examples-standalone-usage)
  * [配合目标分支的 push 事件使用](#git-auto-merge-examples-push-event)
* [最佳实践](#git-auto-merge-best-practices)
  * [使用 squash 自动合并](#git-auto-merge-best-practices-using-squash-auto-merge)
  * [使用 auto 自动选择合并类型](#git-auto-merge-best-practices-auto-select)
  * [建立专用的 CR 群交叉走查自动合并](#git-auto-merge-best-practices-dedicated-cr-group)

## 适用事件 {#git-auto-merge-applicable-events}

`pull_request.mergeable`

## 参数 {#git-auto-merge-parameters}

以下列表先概览 `git:auto-merge` 的全部参数。

* [mergeType](#git-auto-merge-parameters-mergeType)：合并策略
* [mergeCommitMessage](#git-auto-merge-parameters-mergeCommitMessage)：合并点提交信息
* [mergeCommitFooter](#git-auto-merge-parameters-mergeCommitFooter)：合并点脚注，多个用 `\n` 分隔
* [removeSourceBranch](#git-auto-merge-parameters-removeSourceBranch)：合并后是否删除源分支
* [ignoreAssignee](#git-auto-merge-parameters-ignoreAssignee)：是否忽略 `assignee` 强行合并
* [allowAssigneeApprovedMerge](#git-auto-merge-parameters-allowAssigneeApprovedMerge)：处理人已批准时是否允许自动合并

各参数详细说明如下。

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

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

合并策略，默认为 auto：多人提交时走 merge，否则走 squash。

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

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

合并点提交信息。

1. 当合并策略为 `rebase` 的时候，该信息无效，无需填写。

2. 当合并策略为 `merge` 时，默认为 `chore: merge node(merged by CNB)` ，
   会自动追加 PR 引用、评审人名单、PR 包含的提交人名单。举例说明：

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

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

3. 当合并策略为 `squash` 时，默认值为该 PR 的第一条 commit message。
   并会自动追加 PR 引用和评审人名单、PR 包含的提交人名单。举例说明：

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

该配置会产生如下效果：

某个 PR (feat/model-a -> main) 中有两条提交记录：

* 提交记录 1：2023-10-1 日提交

```txt
feat(model-a): 给模块 A 增加一个新特性

由于某某原因，新增某某特性

close #10
```

* 提交记录 2：修复了在 cr 时被指出的一些问题，2023-10-2 日提交

```txt
fix(model-a): 修复评审中指出的问题
```

在自动合并后将会在 main 分支上产生一个这样的提交节点，
即后续的提交记录（也就是提交记录 2）将会被抹掉

```txt
feat(model-a): 给模块 A 增加一个新特性

由于某某原因，新增某某特性

close #10

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

4. 也可以直接指定

如通过环境变量指定为当前 PR 的标题：

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

合并点需要设置的脚注，多个脚注用 `\n` 分隔，仅在 `merge` 和 `squash` 生效。

当合并策略为 `rebase` 的时候，该信息无效，无需填写。

当合并策略为 `merge` 或 `squash` 时，会将传入信息按行加入到脚注中，
再追加 PR 引用、评审人名单、PR 包含的提交人名单。举例说明：

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

合并后是否删除源分支。

源分支与目标分支不同仓库时，该值无效。

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

* type: `Boolean`
* required: `false`
* default: `false`

是否忽略 `assignee`。

当该 PR 有指定 `assignee` （指派人）的时候，本任务不会执行自动合并的逻辑。
因为 `assignee` 的本意就是指派某人手动来处理。

当为 `true` 时，可忽略 `assignee` 强行合并。

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

* type: `Boolean`
* required: `false`
* default: `false`

当 PR 的处理人已经批准时，是否允许自动合并。

当该值为 `true`，且当前 PR 的 `reviewers` 中存在 `state` 为 `approved` 的处理人时，
自动合并会按 `ignoreAssignee` 为 `true` 的逻辑执行。

如果 PR 有多个处理人，只要其中任意一个处理人已批准，即允许自动合并。

## 输出结果 {#git-auto-merge-output}

```javascript
{
    reviewedBy, // String，追加在提交信息后面的提交者信息
    reviewers, // Array<String>, 走查者列表
}
```

## 配置样例 {#git-auto-merge-configuration-examples}

### 单独使用 {#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
```

当分支 main 上的 PR 触发了 `pull_request.mergeable` 事件，
那么会将这个 PR 以 `merge` 的方式自动合并。

### 配合目标分支的 `push` 事件使用 {#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
```

当分支 main 上的 PR 触发了 `pull_request.mergeable` 事件，
那么会将这个 PR 以 `merge` 的方式自动合并。
在合并之后，**最后一个评审通过的评审者会作为触发者**，
触发目标分支（main）上的 `push` 事件，继续执行声明的 `build` 和 `publish` 流程。

## 最佳实践 {#git-auto-merge-best-practices}

### 使用 `squash` 自动合并 {#git-auto-merge-best-practices-using-squash-auto-merge}

使用 `squash` 合并，一次 PR 操作只在目标分支产生一个 Commit 节点，
并且在有权限的情况下删除源分支。

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

### 使用 `auto` 自动选择合并类型 {#git-auto-merge-best-practices-auto-select}

如果多人提交走 `merge` ，否则走 `squash`。

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

### 建立专用的 CR 群交叉走查自动合并 {#git-auto-merge-best-practices-dedicated-cr-group}

1. 走查通过后自动合并，并在提交信息中记录走查者
2. PR 创建/更新时通知评审人

**走查通过后自动合并并通知：**

```yaml title=".cnb.yml"
main:
  pull_request.mergeable:
    - stages:
        - name: CR 通过后自动合并
          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: |
              > CR 通过后自动合并 <@${CNB_BUILD_USER}>
              >
              > ${CNB_PULL_REQUEST_TITLE}
              > [${CNB_EVENT_URL}](${CNB_EVENT_URL})
              >
              > ${REVIEWED_BY}
```

**PR 创建/更新时通知评审人：**

```yaml title=".cnb.yml"
main:
  pull_request:
    - stages:
        # ...省略其他任务
        - 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}
```