Git仓库完整迁移到GitHub的实践指南
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 --depth=1 https://source/repo.git - 分批次获取完整历史：
git fetch --unshallow - 使用SSH协议提高传输稳定性
4.2 LFS文件迁移
如果仓库包含Git LFS文件：
- 确保已安装git-lfs
- 在源仓库执行：
git lfs fetch --all - 推送后验证LFS文件：
git lfs ls-files
4.3 权限与协作设置
迁移后需要：
- 设置团队访问权限
- 配置分支保护规则
- 转移issue和PR（需使用GitHub API或第三方工具）
- 更新CI/CD流水线中的仓库地址
5. 常见问题与解决方案
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| 推送时报错"remote: Permission denied" | 认证失败 | 检查PAT令牌或SSH密钥配置 |
| 部分分支缺失 | 非标准分支名 | 使用git show-ref检查所有引用 |
| 历史提交显示不同 | 邮箱映射问题 | 配置.mailmap文件统一提交者信息 |
| 推送速度极慢 | 网络限制 | 尝试更换SSH协议或使用GitHub CLI |
| LFS文件显示指针 | LFS未正确推送 | 重新执行git lfs push --all |
6. 迁移后的优化建议
- 更新本地克隆的远程地址：
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历史的最可靠选择。