1. 项目背景与核心需求作为开发者我们经常面临代码仓库迁移的需求。最近我就遇到了一个典型场景需要将自建的Git服务如Gitea/GitLab中的项目完整迁移到GitHub SaaS平台。这种迁移不仅涉及代码本身还包括所有分支、标签和提交历史。迁移的主要动机通常包括利用GitHub更完善的CI/CD生态需要与开源社区更紧密协作企业内部代码管理策略调整减少自建Git服务的维护成本2. 迁移前的准备工作2.1 环境检查与工具准备在开始迁移前需要确保本地已安装Git客户端建议版本2.30拥有源仓库的管理员权限在GitHub上已创建目标组织/账号网络连接稳定特别是大仓库需要良好带宽提示对于超过1GB的大型仓库建议在非高峰时段操作并准备好重试机制。2.2 源仓库分析使用以下命令检查源仓库状态git count-objects -vH # 查看仓库体积 git branch -a # 查看所有分支 git tag # 查看所有标签 git remote -v # 查看远程配置3. 完整迁移步骤详解3.1 创建裸仓库克隆这是保证完整迁移的关键第一步git clone --bare https://your-git-server.com/user/repo.git cd repo.git--bare参数会创建一个不包含工作目录的纯仓库副本包含所有历史数据但体积更小。3.2 在GitHub创建目标仓库登录GitHub网页端点击 New repository输入与源仓库相同的名称推荐选择公开/私有设置不要初始化README/.gitignore避免冲突3.3 镜像推送至GitHub在本地裸仓库目录执行git push --mirror https://github.com/user/new-repo.git--mirror参数会推送所有分支包括隐藏的所有标签所有引用和配置完整的提交历史3.4 验证迁移完整性推送完成后进行以下检查分支数量是否匹配git ls-remote --heads origin | wc -l提交历史是否完整git log --oneline | wc -l检查最近提交的SHA值是否一致4. 高级场景处理4.1 大型仓库迁移优化对于超过5GB的仓库使用浅克隆减少初始传输量git clone --bare --depth1 https://source/repo.git分批次获取完整历史git fetch --unshallow使用SSH协议提高传输稳定性4.2 LFS文件迁移如果仓库包含Git LFS文件确保已安装git-lfs在源仓库执行git lfs fetch --all推送后验证LFS文件git lfs ls-files4.3 权限与协作设置迁移后需要设置团队访问权限配置分支保护规则转移issue和PR需使用GitHub API或第三方工具更新CI/CD流水线中的仓库地址5. 常见问题与解决方案问题现象可能原因解决方案推送时报错remote: Permission denied认证失败检查PAT令牌或SSH密钥配置部分分支缺失非标准分支名使用git show-ref检查所有引用历史提交显示不同邮箱映射问题配置.mailmap文件统一提交者信息推送速度极慢网络限制尝试更换SSH协议或使用GitHub CLILFS文件显示指针LFS未正确推送重新执行git lfs push --all6. 迁移后的优化建议更新本地克隆的远程地址git remote set-url origin https://github.com/user/repo.git清理旧的远程分支引用git remote prune origin设置GitHub Actions自动同步如需保留源仓库在README中添加迁移说明我在实际迁移中发现对于包含子模块的仓库需要额外执行git submodule update --init --recursive cd submodule_dir git push --mirror new-submodule-url7. 替代方案比较除了--mirror方法还有其他迁移方式GitHub导入工具优点网页操作简单缺点不支持私有仓库的完整历史手动分支推送git push origin branch1 branch2 git push --tags优点选择性迁移缺点容易遗漏内容第三方迁移工具如git-mirror等专用工具适合企业级批量迁移对于大多数场景--mirror方法仍然是保留完整Git历史的最可靠选择。