在软件开发的生命周期中，版本控制平台的选择往往决定了团队协作的基线。近年来，随着 GitHub 私有仓库政策收紧与 Copilot 定价策略调整，越来越多的开发团队开始评估自托管 Git 基础设施的可行性。Forgejo 作为 Gitea 的社区分支，凭借其轻量级部署、开放架构与完整的功能集，正成为从 GitHub 迁移的热门目标。本文聚焦迁移过程中的工程实践，给出可操作的参数配置与脚本模板。
一、迁移前的评估与策略选择
在启动迁移之前，需要明确两个核心决策：同步模式与迁移范围。同步模式决定数据流向，是一次性克隆还是持续镜像；迁移范围则界定需要迁移的仓库集合，包括组织级仓库的筛选条件。
从 GitHub 迁移至 Forgejo 通常有两种同步策略。第一种是镜像模式（Mirror Mode），在这种模式下，Forgejo 实例与 GitHub 仓库保持实时同步，push 操作会双向传播。这种模式适合需要同时维护两个平台入口的过渡期团队，但维护成本较高，且需要处理 GitHub Actions 与 Forgejo Actions 的兼容性问题。第二种是一次性克隆（Clone Once），将仓库内容完整迁移后断开关联，后续开发完全在 Forgejo 上进行。这种模式更适合有明确迁移计划的团队，可以彻底脱离对 GitHub 的依赖。
在迁移范围上，需要区分个人仓库与组织仓库。个人仓库可以通过 GitHub API 枚举当前用户的所有仓库，并根据名称模式或 star 数量进行筛选。组织仓库则需要考虑权限继承问题，原有的 collaborator 关系在迁移后需要重新建立。建议在迁移前导出一份仓库清单，包含仓库名称、默认分支、原作者信息与权限模型，作为迁移校验的依据。
二、批量迁移脚本的设计要点
批量迁移脚本是整个迁移过程的核心工具。一个健壮的迁移脚本需要处理认证、枚举、创建与同步四个环节。以下是基于 Bash + jq 的最小可行实现框架。
脚本的环境变量配置是第一步。需要配置的变量包括 GitHub 用户名与访问令牌、Forgejo 实例 URL 与令牌、默认的同步策略（mirror 或 clone），以及可选的强制同步开关。以下是典型的环境变量声明：
export GITHUB_USER="your-github-username"
export GITHUB_TOKEN="ghp_your_token_here"
export FORGEJO_URL="https://forgejo.example.com"
export FORGEJO_USER="your-forgejo-username"
export FORGEJO_TOKEN="your-forgejo-token"
export SYNC_STRATEGY="clone" # mirror 或 clone
export FORCE_SYNC="false" # true 时删除目标端多余仓库
在获取仓库列表阶段，脚本通过 GitHub REST API 枚举用户或组织下的所有仓库，并过滤出需要迁移的子集。由于 GitHub API 采用分页机制，一个健壮的实现需要处理 Link 头中的 next 关系，逐页获取完整的仓库列表。API 响应的 JSON 数据通过 jq 工具解析，仅提取仓库名称、描述与默认分支三个关键字段。
仓库创建阶段调用 Forgejo API 的仓库创建端点。每个创建请求需要提供仓库名称、描述、可选的初始化 README，以及访问控制级别。需要特别注意的是，Forgejo API 的认证方式与 GitHub 不同，通常通过 Authorization: token {token} 头部或 query 参数传递令牌。创建成功后，记录返回的仓库 ID 与克隆 URL，为后续的同步步骤做准备。
对于已存在的开源项目，可以直接参考 RGBCube/GitHub2Forgejo 这个仓库提供的完整脚本实现。该脚本支持镜像与克隆两种模式，并提供了环境变量驱动的工作流程。对于偏好 Nushell 的团队，RGBCube 还提供了 Nushell 版本，可以更直观地进行数据处理与管道组合。
三、Webhook 重建与权限迁移
迁移仓库数据只是第一步，迁移后的运维连续性依赖于 Webhook 与权限体系的完整重建。GitHub 上的 Webhook 配置通常包括以下几类：CI/CD 触发 webhook、第三方集成（如 Slack、Discord 通知）、自动化脚本触发，以及发布管理相关的 webhook。迁移时需要逐个记录原配置，并在 Forgejo 上重新创建。
Forgejo 的 Webhook 系统与 GitHub 基本兼容，支持 Payload 发送至指定 URL、包含签名验证的模式。在重建 Webhook 时，建议按照以下清单逐一核对：
第一，确认所有 CI/CD 相关 webhook 的目标 URL。GitHub Actions 的 self-hosted runner 可能在内部网络可达，迁移到 Forgejo Actions 后需要重新配置 runner 地址。第二，检查第三方集成的认证方式。部分集成使用 GitHub App 或 OAuth App 进行认证，迁移到 Forgejo 后需要创建对应的 Forgejo 应用并重新授权。第三，对于使用 GitHub API 进行自动化操作的脚本，需要更新 API 端点前缀。GitHub 的 API 根地址是 api.github.com，而 Forgejo 的 API 根地址是 {forgejo_url}/api/v1。这是一个高频的迁移陷阱，容易导致原有的自动化脚本静默失败。
在权限迁移方面，GitHub 的仓库级权限模型（owner、maintainer、write、read、triage）与 Forgejo 的保护规则存在差异。Forgejo 使用分支保护规则与组织级权限的组合来实现访问控制。建议在迁移后使用 Forgejo API 批量设置分支保护规则，确保默认分支禁止强制推送、需要 PR 审查等策略保持一致。
四、CI/CD 流水线的适配
CI/CD 流水线是迁移过程中最具技术复杂度的环节。GitHub Actions 与 Forgejo Actions 虽然遵循相似的 YAML 语法，但在 runner 注册、秘密管理生态与 Action 市场方面存在差异。
GitHub Actions 的流水线通常以 .github/workflows/*.yml 存储，Forgejo Actions 则以 .forgejo/workflows/*.yml 存储（或在 /.forgejo/workflows/ 目录集中管理）。流水线语法的主要差异集中在 runner 标签与 action 来源上。GitHub Actions 使用 runs-on: ubuntu-latest 或自定义 runner 标签，而 Forgejo Actions 需要使用 runs-on: forgejo 或显式指定 runner 名称。
如果团队使用了 self-hosted runner，迁移后需要在 Forgejo 实例上重新注册 runner。Forgejo Actions 的 runner 通过 act_runner 组件实现，注册过程需要生成唯一实例标识并配置与 Forgejo 实例的通信端点。对于使用 ubuntu-latest 等官方托管 runner 的流水线，Forgejo Actions 目前主要依赖自托管 runner，暂不支持官方托管 runner，这一点需要在迁移评估阶段充分考虑。
秘密管理方面，GitHub Secrets 与 Forgejo Actions Secrets 的调用方式一致，在流水线中通过 ${{ secrets.SECRET_NAME }} 语法引用。迁移时需要将 Secrets 内容导出并重新录入到 Forgejo 的仓库或组织级 Secrets 存储中。需要注意的是，Forgejo Secrets 的作用域与 GitHub 类似，支持仓库级、组织级与实例级三个层级，建议按照最小权限原则分配。
对于使用 marketplace action 的流水线，需要替换 action 来源。GitHub Actions 的 marketplace action 通常以 actions/checkout@v4 的形式引用，而 Forgejo Actions 由于没有官方市场，需要将 action 替换为具体的仓库地址，例如使用 uses: https://forgejo.example.com/gitea/actions/checkout@v4 的形式，或者将 action 仓库镜像到内部 Forgejo 实例中。
五、迁移后的校验清单
迁移完成后，需要进行系统的校验以确保服务连续性。以下是一份可操作的校验清单，涵盖仓库完整性、功能可用性与运维可观测性三个维度。
在仓库完整性层面，需要验证所有分支是否完整迁移，尤其是包含保护规则的默认分支；验证标签（tag）与发布（release）信息是否保留；检查 LFS 管理的大文件是否成功同步；抽样验证二进制文件或大仓库的哈希一致性。
在功能可用性层面，需要验证普通用户可以正常 clone、push 与 pull；验证 PR/MR 工作流正常，包括创建、审查、合并与冲突解决；验证 Webhook 按预期触发并接收正确 payload；验证 CI/CD 流水线可以正常执行。
在运维可观测性层面，需要配置 Forgejo 的日志聚合，监控 API 请求延迟与错误率；设置仓库活动监控，确保 commits、issues 与 PR 的创建量在预期范围内；验证邮件通知与提及（mention）功能的 SMTP 配置。
六、风险与限制
尽管批量迁移脚本可以大幅降低手工操作的成本，但迁移过程仍存在若干需要注意的风险点。
API 速率限制是首要风险。GitHub API 对未认证请求的速率限制为每小时 60 次，认证后为每小时 5000 次。在批量迁移大量仓库时，脚本需要实现退避重试机制，并在达到限制时暂停执行以等待限制窗口过期。
数据一致性是第二个风险点。对于正在活跃开发的仓库，迁移期间可能产生新的 commits。如果采用镜像模式，需要确保镜像频率足够高以捕获最新变更；如果采用克隆模式，需要在迁移前冻结仓库或使用分布式锁确保没有正在进行的 push。
第三个风险点是流水线兼容性。部分流水线依赖于 GitHub 特有的环境变量（如 GITHUB_ACTOR、GITHUB_RUN_ID），迁移到 Forgejo Actions 后需要替换为 Forgejo 环境变量（如 GITEA_ACTOR、GITEA_REPO）。如果流水线中硬编码了 GitHub 相关的逻辑，可能需要较大范围的重构。
七、结语
从 GitHub 迁移至 Forgejo 的工程实践，本质上是一次版本控制平台的去中心化实验。批量迁移脚本、Webhook 重建与 CI/CD 适配这三个环节，构成了迁移的技术主干。对于规模在数十个仓库以内的团队，建议优先采用镜像模式进行过渡，在验证完整后再切换为克隆模式并断开与 GitHub 的关联。对于规模较大的组织，则建议引入迁移编排工具，实现仓库迁移的流水线化管理，并在迁移后建立双写机制以确保数据一致性。
Forgejo 作为开源自托管 Git 平台，在数据主权、隐私合规与成本控制方面具备明确优势。随着社区对 Forgejo Actions 的持续投入与 self-hosted runner 生态的成熟，CI/CD 适配的复杂度将进一步降低。对于追求基础设施自主可控的开发团队，Forgejo 是一个值得认真评估的选项。
参考资料
- GitHub2Forgejo 迁移脚本：https://github.com/RGBCube/GitHub2Forgejo
- PatNei/GITHUB2FORGEJO：Bash 实现的批量迁移工具
- Forgejo 官方迁移文档：https://forgejo.org/docs/next/contributor/repository-migration/
内容声明：本文无广告投放、无付费植入。
如有事实性问题，欢迎发送勘误至 i@hotdrydog.com。