git:auto-merge

1801 字约 6 分钟

git:auto-merge

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

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

使用场景：希望 PR 在检查通过、评审完成后自动合入时使用——例如仓库约定「流水线通过 + 评审人批准即自动合并」，无需人工再点合并按钮。写脚本需要自行申请令牌、判断合并条件，git:auto-merge 把这一步收敛成一个内置任务。

pull_request.mergeable 事件触发条件和时机参考事件。

适用事件
参数
输出结果
配置样例
- 单独使用
- 配合目标分支的 push 事件使用
最佳实践

适用事件

pull_request.mergeable

参数

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

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

各参数详细说明如下。

mergeType

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

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

mergeCommitMessage

type: String
required: false

合并点提交信息。

当合并策略为 rebase 时，该信息无效，无需填写。
当合并策略为 merge 时，默认为 chore: merge node(merged by CNB)，会自动追加 PR 引用、评审人名单、PR 包含的提交人名单。举例说明：

chore: merge node(merged by CNB)

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

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

.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 日提交

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

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

close #10

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

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

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

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

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

close #10

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

也可以直接指定

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

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

mergeCommitFooter

type: String
required: false

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

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

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

.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

合并后是否删除源分支。

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

ignoreAssignee

type: Boolean
required: false
default: false

是否忽略 assignee。

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

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

allowAssigneeApprovedMerge

type: Boolean
required: false
default: false

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

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

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

输出结果

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

配置样例

单独使用

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

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

配合目标分支的 `push` 事件使用

.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 流程。

最佳实践

使用 `squash` 自动合并

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

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

使用 `auto` 自动选择合并类型

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

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

建立专用的 CR 群交叉走查自动合并

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

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

.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 创建/更新时通知评审人：

.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}