Pull:用自动化 Pull Request 保持 GitHub Fork 与上游同步的完整指南
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 目录):
- 入口与调度:src/index.ts(Express + Probot Webhook 服务)、src/worker.ts(BullMQ 后台 Worker);
- 配置解析:src/utils/get-pull-config.ts(实时拉取
.github/pull.yml或生成默认配置)、src/utils/schema.ts(zod 校验与默认值); - 核心业务:src/processor/pull.ts(差异检测、PR 创建、自动合并、冲突处理);
- HTTP 接口:src/router/index.ts(配置校验页、手动触发接口)。
核心特性一览
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。整个流程可以用下面五步概括:
- 归一化与自引用跳过:将
base与upstream统一转为小写,若目标分支与上游分支相同则跳过(防止自我同步)。 - 差异检测:调用 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→ 视为无差异,跳过; - 其余错误记录日志并跳过。
- 提示
- 查找已有 PR:通过
issues.listForRepo(creator限定为机器人)查找机器人此前创建、仍处于打开状态的 PR,按 base/head 精确匹配,避免重复创建(getOpenPR)。 - 创建 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)。 - 自动合并检查:对已有或新建的 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):
- 若
conflictLabel对应的 label 不存在,则自动创建它(颜色ff0000,描述 "Resolve conflicts manually"); - 更新 PR 的 label 列表(
label+conflictLabel)并重写 PR 正文; - 若配置了
conflictReviewers,则把这些人添加为 reviewer,提示他们手工解决冲突。
快速开始:零配置的 Basic Setup
如果你只是想把 Fork 与上游的默认分支(master)保持同步,且没有改动过自己的 Fork,那么完全不需要写任何配置文件:
- 安装 Pull GitHub App(在 GitHub 上选择你的账号或组织,授权它访问目标仓库);
- 等待即可。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,按以下步骤操作:
- 在 Fork 仓库新建一个分支;
- 到 Repository Settings > Branches 中把该分支设为默认分支;
- 在该默认分支下添加
.github/pull.yml; - 访问
https://pull.git.ci/check/{owner}/{repo}校验配置; - 安装 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 你仓库的用户都能自动同步,有两种做法:
- 最简场景:仓库只有一个
master分支,直接引导用户安装 Pull App 即可,无需任何配置; - 多分支场景:需要额外的
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 在起步前给出了两条明确提示,务必先确认:
- 上游仓库必须与你的 Fork 处于同一个 Fork 网络。Pull 的同步依赖
repos.compareCommits与pulls.create在同一网络内完成跨仓库引用,配置中upstream若指向网络外的仓库将无法工作; - 如果你对 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 约束。