SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场github-auto-merge-setup

github-auto-merge-setup

部署与运维

查看项目

更新于 10-27 13:49

技能介绍

用途

该技能面向 GitHub 仓库的自动合并（auto-merge）配置与排障，使用场景包括：

  • gh pr merge --auto 报错失败，或工作流的合并步骤报错；
  • 自动合并在没有任何提示的情况下不生效；
  • 需要为定时依赖更新工作流（dependabot、update-ollama-models、pre-commit autoupdate 等）开启“CI 全绿即合并”；
  • 正在为规则集（ruleset）或分支保护添加必需状态检查，需要判断哪些检查可以安全设为必需；
  • 为可能禁止部分合并方式的仓库选择合并参数（--rebase/--squash）。

主要能力

三层自动合并门槛

GitHub 仅在三个彼此独立的条件同时成立时才启用自动合并；故障出现在不同层会产生不同错误：

  1. 仓库设置 allow_auto_merge（默认关闭）。报错含“Auto merge is not allowed for this repository (enablePullRequestAutoMerge)”。修复：gh api -X PATCH repos/{owner}/{repo} -f allow_auto_merge=true。工作流 YAML 无法开启此项。
  2. 合并方式权限。在禁止该合并方式的仓库上使用对应参数会失败，例如仅允许 rebase 的仓库不能用 --squash。可用 gh api repos/{owner}/{repo} --jq '{allow_squash_merge, allow_rebase_merge, allow_merge_commit}' 查询。
  3. 基线分支保护与阻塞性要求。前两层修好后仍报“Protected branch rules not configured for this branch (enablePullRequestAutoMerge)”，原因是自动合并要等待必需状态检查/评审等阻塞条件，而基线分支没有保护时没有可等待的内容，GitHub 因此拒绝启用。修复方式是在 main 上建立带必需状态检查的规则集或经典分支保护。可用 gh api repos/{owner}/{repo}/rulesets --jq '.[].name' 与 gh api repos/{owner}/{repo}/branches/main/protection 先核查现状。

写合并参数前的一键诊断：

gh api repos/{owner}/{repo} --jq '{allow_auto_merge, allow_squash_merge, allow_rebase_merge, allow_merge_commit}'

必需状态检查的选取规则

永不运行的必要检查会永久阻塞合并。设置前应逐个工作流阅读 on: pull_request: 触发条件，而不是依据过往 PR 的检查列表猜测。只应要求每个 PR 都会运行的检查；WIP 机器人（仅对 WIP/草稿 PR 上报）、check-changes/路径过滤任务、按标签或分支条件执行的 dry-run 发布步骤都容易成为限制条件。矩阵任务需带参数后缀逐一列出，如“unit-tests (Python 3.13, pixi)”与“unit-tests (Python 3.12, pixi)”是不同的检查名。检查名可从真实 PR 获取：gh pr view <pr> --json statusCheckRollup --jq '.statusCheckRollup[].name' 或 gh pr checks <pr>。创建规则集后应重跑 gh pr merge <pr> --auto --rebase，确认 autoMergeRequest 不为 null。

工作流中的合并步骤写法

对于自己开 PR 又合并 PR 的定时工作流，推荐降级处理：

if ! gh pr merge "$PR_URL" --auto --rebase; then
echo "::warning::auto-merge unavailable — PR left open for manual merge"
fi

即发出 ::warning:: 并以 0 退出、留下 PR 待人工合并，避免计划任务常红掩盖真实故障。PR 描述应如实说明自动合并是否会生效。GH_TOKEN 是 gh 的标准令牌环境变量（GITHUB_TOKEN 也可用）。用 GITHUB_TOKEN 创建的 PR 不会触发工作流（防递归），这类 PR 只显示外部检查，不要在其上排查 CI 未运行的问题。

GITHUB_TOKEN 机器人 PR 死锁

当带必需检查的规则集存在、而 PR 由使用 GITHUB_TOKEN 的工作流创建/推送时，现象是自动合并已启用但状态永久 BLOCKED、gh pr checks 只显示外部检查。根因是防递归机制使这类 PR 永远不会触发必需检查，因此与第三层规则集天然不兼容。官方修复是改用 PAT 或 GitHub App 令牌创建/推送 PR（存为仓库 secret 并传给 action 的 token 输入），PAT 推送可触发工作流。已卡住的 PR 可用用户身份执行 gh pr update-branch <pr>（或界面按钮）更新分支来解冻。自派发（self-dispatch）方案需给测试工作流加 workflow_dispatch: 并修补路径过滤任务对空 github.base_ref 的处理，给机器人工作流加 permissions: actions: write 并在建 PR 后 gh workflow run <test-wf.yaml> --ref <branch>；该路径需以实际定时运行验证。另注意：被跳过（skipped）的检查满足必需检查要求；建议规则集设 strict_required_status_checks_policy: false；PUT 更新规则集需提交完整 rules 数组，只发改动片段会被静默忽略；标题以 WIP 开头的机器人 PR 会被 WIP 检查永久阻塞。

与直接推送发布工作流的冲突

在 main 上添加必需检查规则集后，向 main 直接推送的发布工作流会被拒（GH013: Repository rule violations found for refs/heads/main）。若脚本不检查推送退出码，仍会打印成功，随后 gh release create --target main 在旧的 main 顶端自动创建标签并发布 PyPI，形成“半落地发布”：制品为 vX 而 main 的 pyproject 仍是 vX-1，后续发布在“版本已在 PyPI”处失败。诊断方法是比对 main 的 pyproject 版本、最新标签与 PyPI 版本，并在日志中检索 GH013 等特征串。恢复需让 bump 提交落到 main。预防上应审计所有直接推 main 的工作流：推送失败必须硬失败，验证步骤要真正校验分支推送成功，不要用 gh release create --target 作为标签回退。

另需注意：自定义 shell 字符串不会自动获得 -eo pipefail（仅裸 shell: bash 会注入），如 shell: bash -l {0} 需显式加 set -euo pipefail，否则推送失败后仍会继续执行到成功提示。将 GitHub Actions 集成作为规则集 bypass actor 的做法已被否定（会报“Actor GitHub Actions integration must be part of the ruleset source or owner organization”），可行做法是将发布推送改为走 PR：推送 bump 分支、gh pr create、gh pr merge "$PR" --rebase --auto --delete-branch=false，再轮询 gh pr view "$PR" --json state --jq .state 直至 MERGED（有界循环，超时则 ::error:: 并退出 1），因 --auto 会立即返回，不轮询会导致打标签和发布先于实际合并执行。标签推送不受仅限 refs/heads/main 的规则集影响，但 git push --atomic HEAD:main refs/tags/vX 是全有或全无，应在 bump 落到 main 后单独推送标签；rebase 合并会重写 SHA，合并后需 git fetch origin main --tags --force 并核对 origin/main HEAD 提交主题。

使用方式

该技能以说明文档形式提供排障与配置指引，未提供安装命令或代码包。实际执行依赖本机已配置的 GitHub CLI（gh）与相应仓库权限。技能原文的 Instructions 部分标注“TODO: Add specific instructions based on observed patterns.”，即通用操作步骤暂未提供，现有内容为基于实际排障总结的具体规则。

适用场景与限制

适用于 GitHub 仓库、GitHub Actions 工作流与规则集/分支保护相关配置。相关结论来自具体仓库（llamabot）的排障记录，其中部分示例（如具体检查名称、工作流文件名）属于该仓库上下文；其他仓库需按自身工作流核实。自动化脚本、Action 版本及 GitHub 行为可能变化，实施前应重新验证。