automerge-action

当拉取请求准备就绪时自动合并的 GitHub 操作。

<img src="https://yellow-cdn.veclightyear.com/0a4dffa0/70417ee4-e4d2-4c96-a717-e4680c5e993a.svg" width="100%">

添加后，此操作将对带有 automerge 标签的拉取请求执行以下任务：

• 自动将基础分支的更改合并到拉取请求中（仅当分支保护规则中启用了"在合并前要求分支保持最新"时）
• 当拉取请求准备就绪时，将自动合并。该操作只会等待分支保护规则中标记为必需的状态检查
• 将忽略没有配置标签的拉取请求

标签、合并和更新策略是可配置的，详见配置。

在以下情况下，拉取请求被视为准备就绪：

1. 已获得所需数量的审核批准（如果在分支保护规则中启用）
2. 所需的检查已通过（如果在分支保护规则中启用）
3. 拉取请求是最新的（如果在分支保护规则中启用）

拉取请求成功合并后，分支将不会被删除。要在合并后删除分支，请参阅自动删除分支。

---

此功能现在可以直接在 GitHub 中作为 自动合并 使用。 请注意，GitHub 目前不支持自动变基拉取请求。automerge-action 项目仍将继续维护，但鼓励用户对简单的工作流程切换到自动合并，因为它提供了更快速和稳定的体验。

使用方法

创建一个新的 .github/workflows/automerge.yml 文件：

name: automerge
on:
  pull_request:
    types:
      - labeled
      - unlabeled
      - synchronize
      - opened
      - edited
      - ready_for_review
      - reopened
      - unlocked
  pull_request_review:
    types:
      - submitted
  check_suite:
    types:
      - completed
  status: {}
jobs:
  automerge:
    runs-on: ubuntu-latest
    steps:
      - id: automerge
        name: automerge
        uses: "pascalgn/automerge-action@v0.16.3"
        permissions:
          contents: write
        env:
          GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"

有关最新版本，请参阅发布列表。

配置

支持以下合并选项：

• MERGE_LABELS：拉取请求合并所需的标签（使用 MERGE_METHOD）。默认值为 automerge。

  此选项可以是逗号分隔的标签列表，将进行检查。列表中的所有标签都需要存在，否则拉取请求将被跳过（直到所有标签都存在）。以感叹号（!）为前缀的标签在存在时将阻止拉取请求被合并。

  例如，当给定 automerge,!wip,!work in progress 时，任何带有 wip 或 work in progress 标签的拉取请求以及任何没有 automerge 标签的拉取请求都不会被合并。阻止标签优先，所以如果一个拉取请求同时有 wip 和 automerge 标签，它将不会被合并。

  当给定空字符串（""）时，所有拉取请求都将被合并。

• MERGE_REMOVE_LABELS：操作合并拉取请求后自动移除的标签。默认值为 ""。

  此选项可以是逗号分隔的要移除的标签列表。

  当给定空字符串（""）时，不会移除任何标签。

• MERGE_METHOD：将拉取请求合并到基础分支时使用的方法。可能的值有 merge（创建合并提交）， rebase （将分支的所有提交变基到基础分支上） 或 squash （将所有提交压缩成一个提交）。默认选项是 merge。

• MERGE_METHOD_LABELS：设置允许标签决定合并方法 （参见 MERGE_METHOD 的可能值）。 例如，automerge=merge,autosquash=squash。如果没有这样的标签存在， 将使用 MERGE_METHOD 设置的方法。默认值为 ""。

• MERGE_METHOD_LABEL_REQUIRED：设置为 "true" 以要求必须设置 MERGE_METHOD_LABELS 中的一个。默认值为 "false"。

• MERGE_COMMIT_MESSAGE：将拉取请求合并到基础分支时使用的提交消息。可能的值有 automatic（使用 GitHub 的默认消息），pull-request-title（使用拉取请求的标题）， pull-request-description（使用拉取请求的描述）， pull-request-title-and-description 或带有可选占位符的字面值（例如 Auto merge {pullRequest.number}）。 默认值为 automatic。

• MERGE_COMMIT_MESSAGE_REGEX：当使用包含PR内容的提交消息时，使用此正则表达式的第一个捕获子组作为提交消息。可用于将应该与提交一起进入代码库历史的内容与PR相关的样板文本（许可声明、检查列表等）分开。例如，(.*)^---会保留提交消息中直到第一个3横线（Markdown中的水平线）之前的所有内容。默认值为空，表示禁用此功能。

• MERGE_FILTER_AUTHOR：设置后，只有由此作者提出的拉取请求才会自动合并。

• MERGE_FORKS：是否启用从外部仓库合并。默认情况下，来自复刻仓库分支的拉取请求将以与主仓库分支相同的方式合并。将此选项设置为"false"可禁用来自复刻仓库的拉取请求合并。默认值为"true"。

• MERGE_RETRIES和MERGE_RETRY_SLEEP：有时拉取请求的检查运行尚未完成，因此操作将在一段时间后重试合并。重试次数可通过MERGE_RETRIES设置。默认重试次数为6，设置为0则禁用重试逻辑。MERGE_RETRY_SLEEP设置重试间隔时间，单位为毫秒。默认值为5000（5秒），设置为0则禁用重试间隔。

• MERGE_REQUIRED_APPROVALS：所需批准数。默认为0。

• MERGE_DELETE_BRANCH：自动删除分支并非对所有仓库都有效。将此选项设置为"true"可在合并后自动删除分支。默认值为"false"。

• MERGE_DELETE_BRANCH_FILTER：不会被删除的分支列表，以逗号分隔。这不是GitHub的受保护分支列表（那些永远不会被删除），而是额外的需要保护的分支列表。默认值为""。

• MERGE_ERROR_FAIL：将此设置为"true"，当运行期间无法成功合并拉取请求时，操作将以错误代码1退出。

• MERGE_READY_STATE：尝试合并的拉取请求状态。此选项可以是以逗号分隔的状态列表，这些状态将被视为可合并。默认值为clean,has_hooks,unknown,unstable。

支持以下更新选项：

• UPDATE_LABELS：拉取请求需要具备的标签才能进行更新（使用UPDATE_METHOD）。默认值为automerge。

  注意，只有在分支保护规则中启用了"要求分支在合并前保持最新"选项时，才会进行更新。

  此选项可以是以逗号分隔的标签列表，更多信息请参见MERGE_LABELS选项。

• UPDATE_METHOD：更新拉取请求到基础分支时使用的方法。可能的值为merge（创建合并提交）或rebase（将分支变基到基础分支的头部）。默认选项为merge。

  当选项为rebase且变基失败时，操作将以错误代码1退出。这也会在拉取请求页面上显示，提示"此分支存在冲突，必须解决"以及冲突文件列表。

• UPDATE_RETRIES和UPDATE_RETRY_SLEEP：有时拉取请求的检查运行尚未完成，操作无法确定是否需要更新。要多次查询拉取请求状态，可以通过UPDATE_RETRIES设置重试次数。默认重试次数为1，设置为0则禁用重试逻辑。UPDATE_RETRY_SLEEP设置重试间隔时间，单位为毫秒。默认值为5000（5秒），设置为0则禁用重试间隔。

此外，还支持以下常规选项：

• GITHUB_TOKEN：这应始终为"${{ secrets.GITHUB_TOKEN }}"。但在某些情况下，以特定用户身份运行此操作可能会有用（默认情况下，它将以github-actions身份运行）。例如，如果你想在分支保护规则中使用"限制谁可以推送到匹配分支"选项，这可能会很有用。

  要使用此设置手动提供令牌，你需要为用户创建一个个人访问令牌（对于公共仓库，确保勾选public_repo，对于私有仓库，勾选repo）。所有API请求（合并/变基）将以指定用户身份执行。令牌应保密，因此务必将其作为密钥而非环境变量添加到GitHub工作流文件中！

• PULL_REQUEST：如果提供，此操作将尝试合并指定的拉取请求。默认情况下，它将尝试使用GitHub上下文中指定的拉取请求。如果通过此输入提供了拉取请求编号，此操作将在当前仓库中搜索提供的拉取请求编号。如果你想合并另一个仓库中的拉取请求，只需在拉取请求编号前提供仓库标识，如Some-Org/Some-Repo/1234。

• BASE_BRANCHES：如果提供，操作将在基础分支方面受到限制。可以是以逗号分隔的简单分支名称列表（如main,dev）。

你可以在工作流文件中像这样配置环境变量：

env:
  GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
  MERGE_LABELS: "automerge,!work in progress"
  MERGE_REMOVE_LABELS: "automerge"
  MERGE_METHOD: "squash"
  MERGE_COMMIT_MESSAGE: "pull-request-description"
  MERGE_FORKS: "false"
  MERGE_RETRIES: "6"
  MERGE_RETRY_SLEEP: "10000"
  MERGE_REQUIRED_APPROVALS: "0"
  UPDATE_LABELS: ""
  UPDATE_METHOD: "rebase"
  PULL_REQUEST: "1234"

支持的事件

Automerge 可以配置为针对以下事件运行：

• check_run
• check_suite
• issue_comment
• pull_request_review
• pull_request_target
• pull_request
• push
• repository_dispatch
• schedule
• status
• workflow_dispatch
• workflow_run

有关这些事件发生时间的更多信息，请参阅 Github 文档中关于触发工作流的事件和它们的有效负载。

输出

该操作将提供两个输出：

• mergeResult - 操作运行的结果，可能是 skipped、not_ready、author_filtered、merge_failed、merged 之一
• pullRequestNumber - 拉取请求号（如果没有影响到拉取请求，则为 0）

请注意：

1. 当有多个拉取请求受影响时，只有第一个会在输出中可用
2. 要访问这些输出，您的工作流配置必须为 automerge-action 步骤定义一个 id
3. 除非使用个人访问令牌，否则此操作不会触发其他操作，请参阅限制

使用示例：

    steps:
      - id: automerge
        name: automerge
        uses: "pascalgn/automerge-action@v0.15.6"
        env:
          GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
      - name: feedback
        if: ${{ steps.automerge.outputs.mergeResult == 'merged' }}
        run: |
          echo "拉取请求 ${{ steps.automerge.outputs.pullRequestNumber }} 已合并！"

限制

• 当此操作合并拉取请求时，合并不会触发其他 GitHub 工作流。 同样，当另一个 GitHub 工作流创建拉取请求时，此操作也不会被触发。 这是因为工作流运行中的操作无法触发新的工作流运行。然而，workflow_run 事件会按预期触发。
• 当使用个人访问令牌（PAT）来解决上述限制时，请注意，如果发出 PAT 的用户是管理员，并且分支限制不包括管理员，即使对非管理员来说拉取请求不可合并，也可能会被合并（参见 #65）。
• 目前，当拉取请求分支与基础分支不同步时，没有办法触发工作流。在 GitHub 社区论坛上有一个相关请求。

调试

要以完整的调试日志运行操作，请按如下方式更新您的工作流文件：

      - name: automerge
        uses: pascalgn/automerge-action@...
        env:
          GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
          LOG: "TRACE"  # 或 "DEBUG"

如果您需要进一步调试该操作，可以在本地运行。

您需要一个个人访问令牌。

然后克隆此仓库，在仓库中创建一个 .env 文件，例如：

GITHUB_TOKEN="123abc..."
URL="https://github.com/pascalgn/repository-name/pull/123"

使用 yarn 安装依赖，最后运行 yarn it（或 npm run it）。

许可证

MIT