在开源项目尤其是大型monorepo的维护中,平台迁移已成为常见挑战。Zig编译器项目最近从GitHub切换到Codeberg(基于Forgejo),这一过程展示了如何在保留完整git历史、LFS文件、issues/PRs连续性的前提下,实现CI/CD无缝适配,避免任何downtime。这种工程化迁移策略适用于任何规模的monorepo项目,特别是那些依赖GitHub Actions但饱受其不稳定困扰的团队。
迁移核心观点:原子切换 + 双轨管理
迁移的核心是“零丢失、零中断”。传统迁移往往因history丢失或CI中断导致开发者不满,而Zig采用镜像式git推送结合编号隔离,确保所有数据完整转移。证据显示,Zig的36,057 commits和554 MiB仓库大小在Codeberg上完美保留,包括LFS二进制(如测试二进制和构建产物)。这种方法避免了数据导出工具的复杂性,直接利用git原生能力。
可落地参数:
- 预迁移准备清单:
- 备份:
git clone --mirror https://github.com/ziglang/zig.git zig-mirror.git
- LFS迁移:进入镜像仓库,
git lfs fetch --all/origin;验证git lfs ls-files
- Codeberg新建空repo:ziglang/zig(无需初始化commit)
- 推送history:
cd zig-mirror.git && git remote add codeberg https://codeberg.org/ziglang/zig.git && git push codeberg --mirror
- 参数解释:
--mirror推送所有refs(branches/tags),包括LFS via git-lfs。
- 阈值:仓库>500MiB时,分批
git push codeberg +refs/heads/master:refs/heads/master避免超时(Codeberg默认push超时300s,可调至600s)。
这一步耗时视仓库大小,Zig约需10-20min,确保网络稳定(使用git config --global http.postBuffer 524288000增大缓冲)。
Issues/PRs处理:Copy-on-Write语义
直接迁移issues/PRs易导致ID冲突和关联丢失。Zig创新采用“旧GitHub留存、新Codeberg从#30000起”,实现双轨并行。开发者无需手动搬迁,除非需编辑旧项;新讨论无缝继续。“我们仍会审阅GitHub上已开PR”(Zig公告)。
可落地清单:
引用Zig公告:“请勿移动现有GitHub issues/PRs,除非需编辑。”此策略适用于>10k issues的monorepo,回滚成本为零。
CI/CD适配:Forgejo Actions取代GitHub Actions
GitHub Actions“vibe-scheduling”导致Zig CI积压,Forgejo Actions(兼容YAML语法)提供稳定替代。Zig已添加.forgejo/workflows目录,适配自托管runner。
关键参数与配置:
- Runner注册(自托管避免云限额):
./forgejo-runner register --instance https://codeberg.org --token YOUR_TOKEN \
--name zig-ci --labels ubuntu-latest:docker://node:20-bullseye
- labels:
self-hosted,linux,arm64(Zig跨平台需求)
- timeout: 2h(比GH默认1h长,防大型编译)
- Workflow YAML适配(从
.github/workflows复制):
name: CI
on: [push, pull_request]
jobs:
build:
runs-on: self-hosted
steps:
- uses: actions/checkout@v4
with: { fetch-depth: 0 }
- run: zig build -Doptimize=ReleaseFast
timeout-minutes: 120
- 改动:
runs-on: self-hosted;添加cache: { path: ~/.cache/zig }加速。
- 无downtime切换:原子更新
build.zig中CI脚本指向Codeberg origin;并行运行双平台1周,监控zig build-exe成功率>99%。
- 监控点:Prometheus exporter for Forgejo(actions日志),阈值alert:job失败率>5%、queue>10。
回滚策略:若Forgejo负载高,临时git remote set-url origin https://github.com/ziglang/zig.git(5s生效)。
工程化监控与最佳实践
- 参数阈值:
| 方面 |
参数 |
推荐值 |
风险阈值 |
| Git Push |
http.postBuffer |
500MB |
>1GB OOM |
| Runner |
timeout |
2h |
<1h失败 |
| Issues |
起始ID |
30000 |
冲突重置 |
| CI Queue |
concurrency |
5 |
>20 backlog |
- 清单:1.预热Codeberg quota(Zig 554MiB<免费5GB);2.通知社区(Zig公告式);3.捐赠迁移(GitHub Sponsors→Every.org)。
此迁移证明,非营利Forgejo在monorepo场景下媲美GitHub,且更稳定。适用于编译器/大型C++项目。
资料来源: