调用GitHub API合并分支时持续返回409错误的排查求助

问题场景 #

我开发的regex-merge GitHub Action已稳定运行多年，核心功能是将master/main分支的新内容同步到指定分支。近期在某私有仓库中，调用GitHub API执行合并时持续返回409状态码（合并冲突），但本地执行git pull origin master用ORT策略能正常合并，GitHub网页端点击「Update branch」也能完成分支更新。已尝试升级node/octokit依赖，无改善；GitHub在2022年9月将默认合并策略改为ORT，不确定是否与近两个月出现的问题相关，且octokit rest.js和GitHub API均无合并策略配置项。

排查方向 #

• API合并的上下文差异：GitHub API合并基于远程仓库实时状态，若Action调用API时目标分支未同步最新远程提交，会导致合并基准与本地操作不一致。需确认Action是否在合并前拉取了目标分支最新代码，或正确获取分支最新HEAD SHA。
• 仓库合并规则限制：检查私有仓库分支设置，是否开启了「Require status checks to pass before merging」「Require linear history」等严格规则，这类规则可能导致API合并失败，但本地/网页端操作会自动适配或绕过部分校验。同时确认仓库是否允许合并提交、squash合并等选项。
• API与Git本地合并逻辑差异：虽然GitHub默认合并策略改为ORT，但API的合并逻辑和本地git pull的ORT策略可能存在细微区别，比如API不会自动处理文件权限、换行符这类非代码冲突，而本地Git会忽略此类差异。可在本地模拟API合并逻辑：执行git merge --no-ff origin/master，看是否触发冲突。
• Action权限问题：检查Action使用的Token是否拥有仓库写入权限，部分权限不足的场景可能被API包装为409冲突错误，需确保Token具备完整的「repo」权限。

解决方案 #

• 在Action中模拟本地合并流程：放弃直接调用API合并，改用Git命令完成操作，完全对齐本地逻辑：

  git checkout <目标分支>
  git pull origin <源分支> --strategy=ort
  git push origin <目标分支>
  

• 适配API的合并参数：网页端「Update branch」本质是调用POST /repos/{owner}/{repo}/merges接口并自动处理分支状态，可在Action中先获取目标分支最新HEAD SHA，调用API时指定base为该SHA、head为源分支SHA，确保合并基准一致。
• 调整仓库合并规则：若仓库要求线性历史，API无法创建常规合并提交时，可改用squash合并或rebase方式，比如在Action中执行git rebase origin/master后推送，或调用PR合并的API接口指定合并方式。
• 添加重试机制：部分409冲突为临时场景（如多操作并发），可在Action中添加重试逻辑，收到409错误后等待3-5秒再重新调用API。

内容的提问来源于stack exchange，提问作者Alter Lagos