在开源项目尤其是大型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++项目。
资料来源：