Pull:用自动化 Pull Request 保持 GitHub Fork 与上游同步的完整指南

原创2026-10-14 18:31:591,643 阅读
文章标签:开发工具CI/CD

Pull:用自动化 Pull Request 保持 GitHub Fork 与上游同步的完整指南

Pull 是一个运行在 GitHub 上的开源 GitHub App,其核心使命是通过自动创建 Pull Request,让用户的 Fork 仓库始终与上游(upstream)仓库保持同步。本文以官方 README 为主线,结合仓库源码(配置 Schema、处理器、调度与路由实现)逐层展开,帮助你掌握零配置接入、.github/pull.yml 高级配置、五种合并策略的行为差异、手动触发机制,以及自托管部署的关键参数——读完即可在自己的仓库中落地一套"自动同步 Fork"的工程化方案。

项目定位:一个"自动同步 Fork"的 GitHub App

🤖 a GitHub App that keeps your forks up-to-date with upstream via automated pull requests.

这是 README 对 Pull 的一句话定义:它本质是一个 GitHub App + 后台定时任务服务 的组合。App 安装到你的仓库后,会周期性地比较你 Fork 仓库的某个分支与上游对应分支的差异,一旦发现上游有新提交,就自动创建一个 PR 到你的目标分支,并按你配置的合并策略决定是否自动合并。

从仓库结构看,整个项目分为四个层次(对应 src 目录):

核心特性一览

README 列出了 Pull 的五个关键能力,可与源码一一对应:

特性 说明 源码佐证
🔄 自动同步 自动创建 PR 将上游新变更合入 Fork src/processor/pull.ts 的 routineCheck
⚙️ 灵活配置 通过 .github/pull.yml 配置合并策略(merge / squash / rebase / hardreset) src/utils/schema.ts 的 pullMergeMethodEnum
🕒 定时更新 周期性检查上游变更,默认每 6 小时一次 src/utils/helpers.ts 的随机 Cron
👥 团队集成 自动为 PR 添加 assignee 与 reviewer,兼容分支保护与 CI 检查 src/processor/pull.ts 的 addReviewers
🚀 企业就绪 支持 GitHub Enterprise Server(通过 GHE_HOST 环境变量) Dockerfile 中的 GHE_HOST

工作流程:从检测差异到自动合并的源码级拆解

Pull 每次对一个仓库的例行处理,都由 Pull.routineCheck 驱动,逐条遍历配置中的 rules。整个流程可以用下面五步概括:

  1. 归一化与自引用跳过:将 base 与 upstream 统一转为小写,若目标分支与上游分支相同则跳过(防止自我同步)。
  2. 差异检测:调用 GitHub 的 repos.compareCommits 比较 base...upstream,total_commits > 0 即存在差异(src/processor/pull.ts)。源码对三种特殊响应做了兜底:
    • 提示 this diff is taking too long to generate → 视为有差异,继续创建 PR;
    • 提示 not found 或 no common ancestor → 视为无差异,跳过;
    • 其余错误记录日志并跳过。
  3. 查找已有 PR:通过 issues.listForRepo(creator 限定为机器人)查找机器人此前创建、仍处于打开状态的 PR,按 base/head 精确匹配,避免重复创建(getOpenPR)。
  4. 创建 PR:若无现成 PR,则调用 pulls.create,标题格式为 `<a href="https://link.gitcode.com/i/3c1415f80f21f0e4568d5f5fc7ed817c" target="_blank">pull] ${base} from ${upstream}`(见 [src/utils/helpers.ts),随后依次完成锁定会话、补充 assignee 与 label、添加 reviewer(createPR)。
  5. 自动合并检查:对已有或新建的 PR 执行 checkAutoMerge,按规则决定是否合并、用哪种方式合并。

自动合并与五种合并方法的底层实现

processMerge(src/processor/pull.ts)先通过 getMergeableStatus 判断 PR 是否处于可合并状态:

  • mergeable_state === "clean" 直接可合并;
  • mergeable_state === "unstable" 时,仅当规则中 mergeUnstable: true 才允许合并;
  • 状态未知时,最多重试 3 次,每次间隔 4500ms 轮询(isMergeable)。

随后按 mergeMethod 分流:

  • hardreset:不走 GitHub 的合并接口,而是直接调用 git.updateRef 将目标分支的 ref 强制指向上游最新 SHA(force: true,见 hardResetCommit)。这是最彻底的同步方式——目标分支会完全等于上游分支,本地历史被覆盖;
  • merge / squash / rebase:调用 pulls.merge 并传入对应 merge_method(mergePR)。注意一个细节:当 rebase 不可用(rebaseable === false)时,会自动降级为 merge(src/processor/pull.ts);
  • none:只创建 PR 并保持打开,交由人工或 CI 后续处理。

冲突处理

当 PR 的 mergeable === false 时,进入 handleMergeConflict(src/processor/pull.ts):

  1. 若 conflictLabel 对应的 label 不存在,则自动创建它(颜色 ff0000,描述 "Resolve conflicts manually");
  2. 更新 PR 的 label 列表(label + conflictLabel)并重写 PR 正文;
  3. 若配置了 conflictReviewers,则把这些人添加为 reviewer,提示他们手工解决冲突。

快速开始:零配置的 Basic Setup

如果你只是想把 Fork 与上游的默认分支(master)保持同步,且没有改动过自己的 Fork,那么完全不需要写任何配置文件:

  1. 安装 Pull GitHub App(在 GitHub 上选择你的账号或组织,授权它访问目标仓库);
  2. 等待即可。Pull 会周期性地将上游默认分支拉取到你的仓库,默认采用 hard reset(硬重置)策略。

这个"零配置"行为在源码中有明确的兜底实现:当仓库没有 .github/pull.yml 时,getPullConfig 会检查仓库是否为 Fork,若是则基于 parent.default_branch 生成等价于 Basic Setup 的默认配置——mergeMethod 取自环境变量 DEFAULT_MERGE_METHOD(默认 hardreset),mergeUnstable 固定为 true(getDefaultPullConfig)。

需要说明的是,Basic Setup 的零配置能力面向"上游与 Fork 位于同一 Fork 网络"的常规场景;默认配置也仅在仓库是 Fork 且存在 parent 信息时才会生成,普通仓库没有配置会被跳过。

高级配置:用 .github/pull.yml 掌控同步行为

当默认行为不满足需求(例如多分支同步、需要人工审批、需要指定 reviewer)时,可以在默认分支下添加配置文件 .github/pull.yml,按以下步骤操作:

  1. 在 Fork 仓库新建一个分支;
  2. 到 Repository Settings > Branches 中把该分支设为默认分支;
  3. 在该默认分支下添加 .github/pull.yml;
  4. 访问 https://pull.git.ci/check/{owner}/{repo} 校验配置;
  5. 安装 Pull App。

最常用配置(行为与 Basic Setup 一致)

version: "1"
rules:
  - base: master
    upstream: wei:master # 将 `wei` 替换为上游仓库的 owner
    mergeMethod: hardreset
    mergeUnstable: true

完整高级配置

version: "1"
rules: # rules 数组,可配置多条规则
  - base: master # 必填。目标(本地)分支
    upstream: wei:master # 必填。上游仓库,必须与当前仓库处于同一 Fork 网络
    mergeMethod: hardreset # 可选,取值为 [none, merge, squash, rebase, hardreset],默认: none
    mergeUnstable: false # 可选,即使 mergeable_state 不干净也合并 PR,默认: false
  - base: dev
    upstream: master # 必填。也可以是同一 Fork 仓库内的分支
    assignees: # 可选,为 PR 添加指派者
      - wei
    reviewers: # 可选,为 PR 添加审查者
      - wei
    conflictReviewers: # 可选,发生合并冲突时为 PR 指派冲突处理者
      - wei
label: ":arrow_heading_down: pull" # 可选,PR 标签,默认: :arrow_heading_down: pull
conflictLabel: "merge-conflict" # 可选,冲突时使用的自定义标签,默认: merge-conflict

配置参数详解

所有参数的默认值与取值约束都能在 src/utils/schema.ts 的 zod Schema 与 src/utils/schema.test.ts 的测试用例中找到实证:

参数 位置 必填 类型/取值 默认值 说明
version 顶层 是 字符串 "1" — 必须是字符串 "1";version: 1(数字)或 "2" 均会被判为非法
rules 顶层 是 数组,至少 1 条 — 每条规则定义一个"上游 → 目标分支"的同步对
label 顶层 否 字符串 :arrow_heading_down: pull 创建 PR 时打上的标签
conflictLabel 顶层 否 字符串 merge-conflict 合并冲突时打上的标签,不存在时自动创建
base 规则内 是 字符串 — 目标分支,不能为空
upstream 规则内 是 字符串(owner:branch) — 上游仓库的 owner 与分支,须在同一 Fork 网络
mergeMethod 规则内 否 none / merge / squash / rebase / hardreset none 自动合并策略
mergeUnstable 规则内 否 布尔 false 允许在 mergeable_state 为 unstable 时合并
assignees 规则内 否 字符串数组 [] PR 的指派者
reviewers 规则内 否 字符串数组 [] PR 的审查者;包含 / 的元素会被识别为团队名并走 team_reviewers 通道
conflictReviewers 规则内 否 字符串数组 [] 冲突时额外指派的审查者

值得说明的两点实现细节:

  • version 必须为字符串 "1"。Schema 使用 z.string().regex(/^1$/) 校验(src/utils/schema.ts),测试用例明确将 version: 1(数字)与 version: '2' 列入非法配置(src/utils/schema.test.ts);
  • mergeMethod 的默认值是 none,意味着"只创建 PR、不自动合并"。这与 Basic Setup 的 hardreset 默认行为不同——一旦写了配置文件,合并策略就必须显式声明,否则 Pull 只会帮你把 PR 建出来,而不会自动合入。

mergeMethod 五种取值的完整对比(结合 src/processor/pull.ts 的实现):

取值 底层实现 效果
none 不调用合并接口 只创建并保持 PR 打开,等待人工/CI 处理
merge pulls.merge(merge_method: "merge") 产生一条合并提交
squash pulls.merge(merge_method: "squash") 上游所有提交压缩为一条合并
rebase pulls.merge(merge_method: "rebase");不可 rebase 时自动降级为 merge 保持线性历史
hardreset git.updateRef(force: true) 直接强制移动分支 ref 目标分支与上游完全一致,本地历史被覆盖

用官方检查页校验配置

配置写好后,访问 https://pull.git.ci/check/{owner}/{repo} 即可看到解析结果。该页面背后对应 GET /check/:owner/:repo 路由:服务端会拉取实时配置并用 zod Schema 校验,校验失败返回 500,找不到配置返回 404 及提示 Configuration file 'pull.yml' not found(src/router/repo-handler.ts)。

手动触发同步

不想等定时任务?直接访问 https://pull.git.ci/process/{owner}/{repo},服务端会将同步任务入队(GET / POST 均可,见 src/router/index.ts),返回 {"status":"queued"} 后由后台 Worker 异步执行(processHandler)。

自托管场景下还有更直接的方式——利用 scripts/manual-process.ts 在本地手动处理单个仓库:

deno task manual-process <owner>/<repo>

该脚本会从 MongoDB 中查找仓库记录,走与定时任务完全相同的处理链路(getPullConfig → Pull.routineCheck),非常适合调试或绕过 Webhook 服务直接触发。

上游仓库所有者如何引导用户

如果你是一个开源项目的维护者,希望 Fork 你仓库的用户都能自动同步,有两种做法:

  1. 最简场景:仓库只有一个 master 分支,直接引导用户安装 Pull App 即可,无需任何配置;
  2. 多分支场景:需要额外的 docs 等分支时,可以在自己的仓库中加入指向你自己的 .github/pull.yml。这样所有 Fork 你的用户安装 Pull 后,会继承这份配置并自动同步全部声明的分支。

示例(假设 owner 是你的用户名或组织名):

version: "1"
rules:
  - base: master
    upstream: owner:master
    mergeMethod: hardreset
    mergeUnstable: true
  - base: docs
    upstream: owner:docs
    mergeMethod: hardreset
    mergeUnstable: true

定时调度:每 6 小时一次的随机 Cron

Pull 的定时机制并不采用固定整点,而是为每个仓库生成一个随机的每 6 小时一次的 Cron 表达式:随机分钟 + 随机起始小时,然后以 6 小时为间隔生成四个执行点(getRandomCronSchedule)。这一设计可以有效错峰,避免大量仓库在同一时刻集中触发 GitHub API。仓库加入调度后即获得该 Cron,且会持久化复用已有调度(src/utils/get-repository-schedule.ts)。

调度任务由 src/worker.ts 中的 BullMQ Worker 消费:默认并发数 10,已完成/失败的任务各保留最多 1000 个、存活 1 小时,并监听 SIGINT/SIGTERM 优雅退出。单个仓库的处理设有 60 秒超时保护(src/processor/index.ts),超时任务会被判定失败并记录日志。

运行环境与自托管部署

Pull 基于 Deno 2.0 + TypeScript + Probot 构建(deno.json 中版本为 2.0.0-alpha.4),依赖 MongoDB(存储仓库/安装记录)、Redis(BullMQ 任务队列)。仓库内置了完整的开发与运维命令:

# 启动 Webhook + 调度服务(默认会先做一次全量同步)
deno task dev

# 跳过启动时的全量同步
deno task dev:skip-full-sync

# 启动后台 Worker
deno task worker

# 全量同步所有已安装仓库
deno task full-sync

# 手动处理单个仓库
deno task manual-process <owner>/<repo>

# 测试 / 静态检查
deno test --allow-net --allow-env --allow-read
deno lint && deno fmt --check && deno check .

关键环境变量

Dockerfile 明确区分了必需与可选变量:

  • 必需:APP_ID、APP_NAME、APP_SLUG、WEBHOOK_SECRET、PRIVATE_KEY(GitHub App 的安装凭证);
  • 可选:PORT(默认 3000)、WEBHOOK_PATH(默认 /api/github/webhooks)、CONFIG_FILENAME(默认 pull.yml)、DEFAULT_MERGE_METHOD(默认 hardreset)、LOG_FORMAT、LOG_LEVEL、GHE_HOST(GitHub Enterprise Server 时设置)等。

这些变量的读取集中在 src/configs/app-config.ts:botName 由 APP_SLUG 推导为 pull[bot](机器人身份),configFilename 决定配置文件文件名,defaultMergeMethod 决定零配置场景的合并策略。

Docker Compose 一键部署

docker-compose.yml 提供了开箱即用的编排:app(Webhook 服务)、worker(默认 3 副本)、mongodb(mongo:8)、redis(redis:7.4)。使用方式:

# 将 GitHub App 凭证写入 ./.env 后启动
docker compose up -d

# 手动执行一次全量同步
docker exec -it pull-app-1 deno task full-sync

# 非 Swarm 模式下扩容 Worker
docker compose up -d --scale worker=3

前置条件与注意事项

README 在起步前给出了两条明确提示,务必先确认:

  1. 上游仓库必须与你的 Fork 处于同一个 Fork 网络。Pull 的同步依赖 repos.compareCommits 与 pulls.create 在同一网络内完成跨仓库引用,配置中 upstream 若指向网络外的仓库将无法工作;
  2. 如果你对 Fork 做过修改,请先做好备份。尤其是使用 hardreset(默认合并策略)时,目标分支会被强制重置为上游状态,本地独有提交将被直接覆盖,这一点与"自动同步"的便利性相伴,需要在使用前想清楚。

小结

Pull 用一个配置文件加一个 GitHub App,把"Fork 同步"这一高频维护动作变成了完全自动化的流水线:routineCheck 检测差异、自动创建 PR、按 mergeMethod 合并、冲突自动标注并指派 reviewer,再辅以每 6 小时一次的随机定时与可手动触发接口。无论你是只想零配置同步 master 分支的个人开发者,还是需要多分支、多团队协同的上游维护者,都可以在这套机制上找到对应的落地方式。

本仓库为只读镜像,你可以继续阅读 src/processor/pull.ts 了解完整的 PR 生命周期处理,或通过 src/utils/schema.test.ts 中的 8 组合法与 20 组非法配置用例,进一步验证自己手写的 pull.yml 是否符合 Schema 约束。

登录后查看全文
pull