接手上游项目时做的第一件事通常是 fork 一份到自己账号下，真正麻烦的在后头：上游三天两头合 PR，你那份 fork 还停在原地。我有一阵同时维护七八个 fork，网页上那个 Sync fork 按钮点到手酸，还得挨个切分支点。后来干脆把这件事整个交给 GitHub Actions，一个 cron 表达式加二十来行 YAML，fork 落后这件事就再没操过心。下面这套做法适合把 fork 当只读镜像、个人信息源、部署源或 submodule 依赖的人，也适合长期跟进上游、随时准备提 PR 的开发者；如果你只是偶尔翻别人的仓库看一眼，网页按钮其实更省事，不必折腾。
1. Fork 落后的代价，比"版本旧一点"严重得多
很多人对 fork 落后的认知停留在"我的代码不是最新的"，但实际影响分三层。最浅的一层是心理上的不踏实；中间一层是实际成本：当你基于半年前的 fork 提 PR，diff 里会混进一堆上游早已改掉的内容，review 的人第一句就是让你 rebase，一次 rebase 可能耗掉半小时；最深的一层是下游消费方——你的 fork 如果在某台机器上做部署源、在另一个仓库里做 submodule、或者被别人用go get之类的包管理器引用，那它落后就意味着别人拿到的是旧行为、旧依赖甚至旧漏洞。
所以判断"要不要把同步自动化"的标准，不是你 fork 了多少个仓库，而是这个 fork 有没有下游。纯粹收藏用的仓库，落后就落后，无所谓。
1.1 网页按钮的隐藏成本
网页那个 Sync fork 看着方便，实际操作链路是：打开仓库页面、看它提示 behind 多少、点按钮、等几秒、刷新确认。单个仓库大概二十秒，但要命的是它打断了你的注意力——你本来在写代码，突然去点同步，回来就得重新进入状态。更麻烦的是多分支：默认分支点完，dev、release这些分支得切过去一个个点，网页按钮对非默认分支的支持远不如命令行顺手。我统计过自己最夸张的一周，光点这个按钮就花了十几分钟，而且全是碎片时间。
1.2 本地写脚本为什么不长久
第二种常见做法是本地加个 upstream 远端，写个 shell 脚本git fetch upstream && git merge upstream/main && git push，挂在 crontab 里跑。这方案本身没毛病，问题在"本地"两个字：脚本依赖你那台机器开机、联网、git 凭据没过期、工作区没有未提交的改动。我在这上面翻过车——脚本静默失败了两周，因为某次改代码时 push 被拒绝，之后的git merge一直卡在冲突状态，crontab 每天照跑，每天失败，而我根本不知道。自动化最难的不是跑通，是失败了有人知道。
1.3 什么时候该上 Actions
我的经验阈值是这样的：fork 数量超过三个，或者任意一个 fork 的上游仓库每周都有提交，或者这个 fork 被别的东西引用（部署、submodule、CI 依赖），就值得上 Actions。反之，一年更新两次的冷门仓库，手动点两下更划算。
方案对比如下，可以对着自己的情况选：
| 方案 | 触发方式 | 多分支支持 | 失败可见性 | 维护成本 |
|---|---|---|---|---|
| 网页 Sync fork | 手动 | 差，需逐个点 | 无 | 极低但不能忘 |
| 本地 cron 脚本 | 定时 | 好 | 差，静默失败 | 中，依赖本机环境 |
| GitHub Actions | 定时 + 手动 | 好，可用矩阵 | 好，有执行记录和通知 | 一次配置长期受益 |
| 平台自带镜像功能 | 自动 | 取决于平台 | 一般 | 低，但受平台限制 |
Actions 的核心优势就在最后一列：它跑在别人的机器上，不依赖你开机，而且每次执行的日志都留着，失败会给你发邮件，这三点恰好是前两种方案最缺的。
2. 一次自动同步，底层到底发生了什么
要把这套东西配稳，得先弄清楚 Actions 执行器在干什么。它本质上就是一台临时虚拟机，每次运行都是全新的、干净的、跑完即销毁。这跟你在自己电脑上跑脚本的体验完全不同——没有历史缓存，没有你之前的 git 配置，没有全局的凭据文件。
2.1 执行器看到的是一张白纸
工作流启动后，默认情况下执行器上什么都没有。你必须在第一个步骤里用actions/checkout把你的 fork 拉下来，否则后续所有 git 命令都会报"不是 git 仓库"。这一点新手特别容易忽略，因为本地跑脚本时你天然就在仓库目录里。拉下来之后，origin指向的是你的 fork，这个远端是只读加上你给它的写入权限；而上游仓库的地址在默认情况下完全不存在，必须手动git remote add upstream加上去。很多教程省略这一步的解释，导致读者以为 fork 天然知道自己的上游是谁——不是的，fork 关系是网页层面的记录，git 层面两者之间没有任何联系。
2.2 上游分支和本地分叉的关系
同步的本质是三个引用的对齐：上游的upstream/main、你本地的main、你 fork 远端的origin/main。完整链路是git fetch upstream把上游最新提交抓进本地对象库，git merge upstream/main把它合进你的main（这时可能产生合并提交，也可能冲突），最后git push origin main把你本地的main推到远端。理解这条链路之后，各种报错就都好解释了：rejected (fetch first)说明origin/main走在了你前面；refusing to merge unrelated histories说明本地历史被截断了（浅克隆的锅）；already up to date说明上游没动，什么都不用做。
2.3 权限才是真正的分水岭
绝大多数人第一次配置失败，卡的不是 git 命令，是权限。GitHub 的默认令牌（GITHUB_TOKEN）是给工作流临时用的，它能推送到当前仓库，但有两条硬限制你必须知道：
第一，它不能修改.github/workflows/目录下的文件。如果上游恰好改了自己的工作流文件，这次同步就会被拒，报错大意是"refusing to allow a token to create or update workflow file"。这个坑极其隐蔽，因为平时同步几十次都没事，偏偏上游动了工作流那一次失败。
第二，用默认令牌推送产生的新提交，不会触发其他工作流。这其实是个防递归保护，如果你的仓库靠 push 触发构建或部署（比如自动发布静态站点），那同步完之后流水线不会自动跑起来，需要额外处理。
想绕开这两点，就得自建一个细粒度访问令牌存到 Secrets 里。这就是下面配置里那个SYNC_PAT的由来。
3. 一份可以直接抄的工作流配置
3.1 文件位置、触发条件和第一个坑
工作流文件必须放在仓库根目录的.github/workflows/下，扩展名是.yml或.yaml。定时触发（schedule）有个硬性前提：工作流文件必须存在于默认分支上，放在其他分支的定时任务不会被执行。
还有个几乎人人都会踩一次的坑：fork 过来的仓库，Actions 默认是关闭的。你 fork 完打开 Actions 标签页，会看到一个提示让你确认启用工作流。不点那个按钮，配置文件写得再对也不会跑。我当初排查了一个多小时，最后发现就是没点这个确认。
触发条件我一般配两个：schedule定时跑，workflow_dispatch留手动入口。定时不要写整点，也不要写*/5这种极限间隔——GitHub 在高峰期对定时任务有排队延迟，整点是最挤的时段。我习惯用类似17 3 * * *这样的偏门分钟数，实测下来平均延迟比整点小很多。cron 用的是 UTC 时间，北京时间要减 8 小时。
3.2 完整配置与逐段拆解
name: sync-fork on: schedule: - cron: '17 3 * * *' workflow_dispatch: permissions: contents: write concurrency: group: sync-fork cancel-in-progress: false jobs: sync: runs-on: ubuntu-latest steps: - name: 拉取自己的 fork uses: actions/checkout@v4 with: fetch-depth: 0 token: ${{ secrets.SYNC_PAT }} - name: 配置提交身份 run: | git config user.name "sync-bot" git config user.email "sync-bot@users.noreply.github.com" - name: 关联上游并抓取 run: | git remote add upstream https://github.com/上游用户名/上游仓库名.git git fetch upstream --prune --tags - name: 合并上游默认分支 run: | git checkout main git merge --no-edit upstream/main - name: 推回自己的 fork run: | git push origin main几个关键点单独说。
fetch-depth: 0是必须的。默认 checkout 只抓最近一次提交，本地历史是断的，跟上游一合并就报unrelated histories。这个参数让执行器抓完整历史，代价是稍微慢几秒，完全值得。
concurrency是防止两次定时任务撞车。如果上一轮还在跑，下一轮又启动，两边同时推送就有概率冲突。设好并发组，后一轮会排队等待而不是并行。
git merge --no-edit用默认的合并策略，会保留一个合并提交。如果你希望历史保持线性、看起来更像上游的延续，把 merge 换成git rebase upstream/main更漂亮，代价是将来自己提 PR 时需要额外注意历史重写的问题。
最后一步推送，如果你的默认分支叫master或者别的名字，记得三处都改掉：checkout 的分支、merge 的目标、push 的目标。
3.3 令牌怎么建、放哪、多久换一次
进你的 fork 仓库，Settings → Secrets and variables → Actions → New repository secret，名字填SYNC_PAT，值粘贴令牌。
令牌本身建议用细粒度令牌，而不是传统的经典令牌。创建时把仓库范围限制到"只有自己的这个 fork"，权限里给Contents: Read and write；如果你确实需要同步上游对工作流文件的修改，再额外加Workflows: Read and write。权限给到这么小，即使令牌泄露了，损失范围也可控。
注意：细粒度令牌有有效期，最长一年，到期当天所有同步任务会集体失败，报错是认证失败。建议在日历上提前一两周设个提醒，或者干脆在仓库里开一个 issue 记录到期日。
放好之后，先在本地验证一下令牌有效：git ls-remote https://<token>@github.com/你的用户名/你的仓库.git。能列出分支就说明令牌没问题，比在工作流里试错快得多。
4. 跑起来之后最容易卡住的几个地方
配置能跑通是一回事，长期稳定是另一回事。下面这些是我自己在日志里真见过的。
4.1 推送被拒的典型报错
我把常见报错整理成了一张对照表，遇到问题按图索骥比盲猜快：
| 报错关键词 | 根因 | 处理方式 |
|---|---|---|
Permission to ... denied | 令牌权限不足、过期，或 checkout 时没注入令牌 | 检查 Secrets 名称是否写对，令牌是否过期，checkout 是否显式传了 token |
refusing to allow a token to create or update workflow | 上游改了工作流文件，而令牌没有工作流权限 | 给令牌补 Workflows 权限，或干脆排除该文件 |
refusing to merge unrelated histories | 浅克隆导致本地历史断裂 | fetch-depth: 0 |
rejected ... (fetch first) | 远端分支比你本地新，通常是手动提交过或并发运行 | 先git pull --rebase，或加concurrency防撞车 |
could not read Username | 令牌没有以正确形式写入远端地址 | 检查 checkout 的 token 参数是否正确引用 Secrets |
页面仍显示N commits behind | 上游在你推送之后又有新提交 | 正常现象，等下一轮；急的话手动触发一次 |
rejected这条特别值得展开。它多半出现在你在网页上直接编辑过文件、或者同时开了两个工作流的情况下。加了concurrency能解决大部分，剩下的建议在推送前先git pull --rebase origin main，把远端的新提交先叠上来。
4.2 定时任务"没触发"的真相
有几种情况会让你以为工作流坏了：
第一种，cron 在 UTC 时区。你按北京时间算的0 2 * * *其实是早上十点，等错时间了。
第二种，仓库连续 60 天没有任何活动，定时任务会被自动停用。这是个明确的机制，不是 bug。判断方法很简单：去 Actions 页面手动触发一次workflow_dispatch，如果手动能跑、定时不跑，基本就是这个原因。想维持定时，最简单的办法就是让仓库保持一点活动，或者接受手动触发。
第三种，定时任务在高峰期会延迟甚至跳过。GitHub 的调度不是精确定时器，负载高的时候延迟十几分钟很常见，偶尔还会整轮不跑。所以别把同步时间卡在关键节点前——比如你依赖 fork 做部署源，就不要把同步设在发布前五分钟。
第四种，工作流文件只存在于非默认分支。前面提过，定时触发只认默认分支上的文件。
4.3 冲突、非快进和上游强推
真正麻烦的是你自己也在 fork 上改过东西。这时 merge 很可能冲突，工作流会直接失败，日志里能看到CONFLICT字样。两条路可选：一是接受失败，人工进去处理冲突再提交；二是让自动化偏向一边，比如在合并时加-X theirs表示冲突时采用上游版本。
git merge --no-edit -X theirs upstream/main注意：
-X theirs会默默丢掉你本地在同一位置的改动，用之前一定想清楚。它适合"这个 fork 我只当镜像用，本地改动可以放弃"的场景，不适合你在 fork 上有长期维护的分支。
还有一种情况是上游做了强制推送（force push），把历史重写了。这时候普通的 merge 会因为缺少共同祖先而失败，或者把已被删除的提交又合并回来。如果你的 fork 是纯镜像、自己没有提交，最干净的做法是硬重置：
git fetch upstream --tags git checkout main git reset --hard upstream/main git push --force-with-lease origin main--force-with-lease比--force安全，它会在远端分支被别人动过时拒绝推送，避免误覆盖。我一般只在纯镜像仓库上用这个组合，有自己提交的仓库坚决不用重置。
5. 按自己仓库的情况做几种改造
基础版跑稳之后，可以按需要往上加东西。
5.1 多分支同步用矩阵展开
要同步多个分支，不用复制粘贴一堆 job，用矩阵更清爽：
jobs: sync: runs-on: ubuntu-latest strategy: fail-fast: false matrix: branch: [main, dev, docs] steps: - uses: actions/checkout@v4 with: ref: ${{ matrix.branch }} fetch-depth: 0 token: ${{ secrets.SYNC_PAT }} - run: | git remote add upstream https://github.com/上游用户名/上游仓库名.git git fetch upstream --prune git checkout ${{ matrix.branch }} git merge --no-edit upstream/${{ matrix.branch }} git push origin ${{ matrix.branch }}fail-fast: false很重要，它让某个分支失败时其他分支继续跑完，而不是整批中断。这样你在一轮日志里就能看到全部分支的状况，不用反复重跑。
5.2 只同步标签，或者只盯某个目录
有些仓库你只关心它的版本标签，不关心分支历史。那就把推送目标改成标签：
git fetch upstream --tags git push origin --tags但要注意，标签只会增加不会自动删除，上游删掉的旧标签你这边会一直留着。想清理的话得显式删除，这属于破坏性操作，建议加workflow_dispatch手动触发，别放进定时任务里。
只想跟踪某个子目录的变化，Actions 层面做不了细粒度挑选，正确做法是让同步照常进行，然后在后续的构建或部署阶段只处理你关心的目录。硬要在 git 层做路径过滤，维护成本远高于收益。
5.3 加一道结果校验，别只看"绿色对勾"
工作流跑成功，不等于同步成功。有一种情况日志全绿，但你的 fork 仍然落后——上游在推送之后又合了新提交，或者你设的 cron 频率本来就追不上上游的活跃度。
我习惯在最后加一步轻量校验，把同步后的实际状态打出来：
git log --oneline -5 git rev-list --count upstream/main ^main第二行会输出你本地落后上游多少个提交，日志里一眼就能看到。如果你希望失败时收到明确提醒，可以在这步加上判断：落后数量大于零就退出非零状态码，让整轮任务标记为失败，这样 GitHub 的失败邮件就成了一层兜底告警。
6. 跑了大半年之后的一点体会
这套东西我从单个仓库的试验品，扩到十来个 fork 的批量配置，中间翻过的车基本都在前面写了。最大的教训是不要指望定时任务精确可靠：它是一次性执行器、共享调度队列、60 天自动停用的组合，本质上是"尽力而为"，不是"保证送达"。我的处理方式是把关键仓库的同步频率设得比实际需要高一点，同时在真正要用之前手动触发一次确认，两秒钟的事，比事后排查省心得多。
另一个体会是权限要一次给足但不要给多。我早期图省事用了经典令牌加全仓库权限，后来发现只要一个仓库的令牌泄露，影响面就不可控，赶紧全换成了细粒度的。换的过程有点烦，但换完之后心里踏实很多。
如果你的上游特别活跃，一天十几个提交，那定时同步其实追不上，这时候更合理的选择是直接基于上游做开发、把自己的改动做成 PR，而不是维护一个永远落后的 fork。工具的边界想清楚了，才不会被它牵着走。
