迁移前必须做的三项核心准备
很多人觉得迁移就是“复制粘贴仓库”，但真正关键的工作其实在迁移前。就像搬家前要先列物品清单，仓库迁移前也得把“家底”摸清楚，不然很容易漏东西。
第一步是仓库完整性检查
。你得确认当前GitHub仓库里有没有“藏起来”的关键数据。比如去年那个电商项目，他们迁移时漏了三个子模块（submodule），导致新仓库跑起来就报错——因为子模块的链接还指向GitHub的旧地址。你可以通过git submodule status命令检查是否有子模块，有的话要单独记录每个子模块的URL和版本。 别忘了标签（tag）和里程碑（milestone），尤其是标记了发布版本的标签，比如v1.2.0这种，丢了可能影响版本回溯。 第二步是权限体系梳理。这是最容易翻车的环节。我见过太多团队只记了管理员权限，却漏了分支保护规则——比如主分支要求代码审核才能合并，或者某些分支禁止强制推送。你可以在GitHub仓库的“Settings→Branches”里把所有保护分支的规则截图保存，包括谁有合并权限、是否需要通过CI检查等。如果团队用了 CODEOWNERS 文件（指定代码审核人），也要把这个文件单独备份，不然迁移后代码审核流程会断。 第三步是环境与工具准备。你需要确保本地有足够的磁盘空间——我去年迁移一个5GB的仓库，加上缓存文件总共占了12GB，所以提前清理下磁盘。 Git版本 用2.20.0以上，旧版本可能不支持某些镜像克隆参数。如果仓库很大（比如超过10GB），最好用SSH协议克隆，HTTPS容易因为超时失败，你可以在GitHub的“Settings→SSH and GPG keys”里添加本地SSH密钥，这样克隆速度会快30%左右。
这里有个检查清单，你可以打印出来逐项打勾：
| 检查项 | 检查方法 | 常见问题 |
|---|---|---|
| 子模块 | 执行 git submodule status |
子模块URL未更新导致依赖拉取失败 |
| 分支保护 | 截图GitHub仓库分支设置页面 | 保护分支权限丢失导致误合并 |
| 大文件 | 用 git lfs ls-files 检查LFS文件 |
LFS文件未迁移导致二进制文件损坏 |
准备工作还要包括目标GitLab仓库的创建——记得在GitLab上新建一个“空白项目”，不要勾选“初始化仓库”（不然会有初始提交，导致推送冲突）。如果团队用了GitLab的组权限，提前在目标组里配置好成员角色，比如开发者、维护者的权限，和GitHub保持一致。
零丢失迁移全流程：从克隆到验证的每一步
准备工作做好后，正式迁移其实就像“精密手术”——每个步骤都有讲究，错一步可能就影响数据完整性。我分四个关键阶段来讲，你跟着做就能把仓库“原封不动”搬到GitLab。
第一阶段：用镜像克隆完整拉取数据
。很多人习惯用git clone直接拉仓库，但普通克隆只会复制默认分支（通常是main或master），其他分支和标签都不会拉下来。正确的做法是用镜像克隆：先在本地执行git clone mirror https://github.com/你的用户名/仓库名.git，这个命令会把GitHub仓库里所有分支、标签、提交历史甚至隐藏的引用（比如PR的临时分支）都完整复制下来，生成一个“镜像仓库”。
为什么要用mirror？打个比方，普通克隆像复印一本书的正文，而镜像克隆是连封面、版权页、注释页一起复印，连夹在书里的书签都不会漏。去年帮教育类项目迁移时，他们一开始用普通克隆，结果发现5个开发分支没复制过来，后来重新用镜像克隆才解决。克隆完成后，你可以进入仓库目录，用git branch -a检查是否所有分支都在，git tag确认标签完整。
第二阶段：推送镜像到GitLab
。克隆完成后，需要把本地镜像推送到GitLab的新仓库。先执行cd 仓库名.git进入镜像仓库目录，然后用git remote set-url origin https://gitlab.com/你的组名/新仓库名.git把远程地址改成GitLab的地址。这里要注意，如果你用HTTPS推送，可能需要输入GitLab的用户名和访问令牌（在GitLab的“Settings→Access Tokens”里创建，勾选“write_repository”权限）；用SSH的话要确保本地SSH密钥已添加到GitLab。
推送命令用git push mirror origin，这个命令会把所有本地镜像数据推送到GitLab，包括分支、标签和提交历史。推送过程可能需要几分钟到几小时，取决于仓库大小——我迁移过一个2GB的仓库，用公司网络推了40分钟，期间不要中断连接，不然可能导致部分数据推送失败。
第三阶段：关键配置同步与权限重建
。代码和历史记录迁移后，别以为就结束了——权限、分支保护、CI/CD这些“软配置”如果不同步，团队协作会立刻出问题。比如上个月帮一个SaaS项目迁移，他们迁移后没重建Webhook，导致代码合并后CI自动部署没触发，线上版本没更新，用户投诉了才发现。
分支权限和保护规则需要手动同步（目前没有完全自动化的工具）。你可以对照迁移前截图的GitHub分支保护规则，在GitLab的“Settings→Repository→Protected branches”里重新配置：比如设置主分支需要至少1个审核通过才能合并，禁止强制推送，指定哪些人有合并权限。如果团队用了CODEOWNERS文件，直接把GitHub仓库里的.github/CODEOWNERS文件复制到GitLab的.gitlab/CODEOWNERS（注意目录名从.github改成.gitlab）。
CI/CD和Webhook部分，GitHub的.github/workflows目录里的配置文件不能直接用在GitLab上，需要转换成GitLab的.gitlab-ci.yml格式。你可以参考GitLab官方提供的CI/CD配置转换指南{rel=”nofollow”}，里面有详细的语法对比。Webhook的话，在GitLab的“Settings→Webhooks”里重新添加，比如Jenkins的触发地址、Slack通知链接，和GitHub保持一致。
第四阶段：迁移后验证三步法
。做完上面所有步骤，一定要验证迁移是否成功，不然上线后发现问题更麻烦。验证分三步：
git log origin/main对比本地GitHub仓库和GitLab远程仓库的提交哈希值，完全相同才算成功。 记得，验证过程最好在非工作时间进行，比如周五晚上，这样即使有问题，周末有时间修复，不影响周一的开发。
迁移完成后，你可能会问：旧的GitHub仓库怎么办？ 先设为“私有”并添加公告，告诉团队“此仓库已迁移，新仓库地址是XXX”，保留1-2个月再删除，给大家留个过渡期。
按这些步骤做完，你会发现GitHub到GitLab的迁移其实没那么复杂——关键是准备充分、步骤精准。如果你在某个环节卡住了，比如推送时提示“权限被拒”，先检查GitLab的访问令牌权限是否正确；如果历史记录不完整，回头看看是不是漏了镜像克隆的步骤。
迁移不是终点，而是新协作的开始。你可以在评论区告诉我：你的团队迁移是因为GitLab的CI/CD更强大，还是因为权限管理更灵活？或者遇到了其他问题，我会帮你分析解决。
GitHub和GitLab的分支保护规则确实不是“一键迁移”的，就像两个品牌的门锁，钥匙不能通用，得自己动手配新钥匙。你知道吗？去年帮一个金融项目迁移时，他们就因为没注意这个细节，导致主分支合并时少了审核环节，差点把未测试的代码推上去——后来查了才发现，GitHub里设置的“必须2人审核才能合并”，在GitLab里默认是关闭的，得手动打开。
其实两者的核心功能类似，但名字和设置入口不一样。比如GitHub里的“Require pull request reviews before merging”（拉取请求必须审核才能合并），在GitLab里叫“Merge request approvals”（合并请求审批），虽然功能对应，但GitLab能设得更细，比如可以指定“只有架构师审核通过才能合并到主分支”，或者“前端代码必须前端负责人审核”，这是GitHub的基础版没有的。还有分支保护里的“禁止强制推送”，GitHub在“Branch protection rules”里直接勾选就行，GitLab则要在“Protected branches”里找到对应分支，把“Allow force pushes”设为“Never”。这些细节如果迁移前不记下来，很容易漏配。
所以迁移前一定要做“截图存档”——打开GitHub仓库的“Settings→Branches”，把每个保护分支的规则都截下来，特别是审核人数、要不要通过CI检查、能不能强制推送这些关键项，最好用表格列出来，比如“主分支：审核2人、禁止强制推送、必须通过lint检查”。到了GitLab这边，就按这个表格一条一条对着配：先在“Settings→Repository→Protected branches”里找到要保护的分支，点“Edit”，然后把“合并请求审批”设成对应的人数，“强制推送”选“不允许”，再去“Settings→CI/CD→General pipelines”里把需要的CI检查勾上。
配完之后千万别觉得万事大吉，一定要用测试账号试一下。去年那个电商团队，配置完后看着设置页面觉得没问题，结果开发同学提了个合并请求，发现还是能直接合并——后来才发现，GitLab里的“审批规则”需要手动“启用”，光填了审核人数没点“保存”等于白搭。你可以建个测试分支，用普通成员账号提个合并请求，看看会不会弹出“需要审核”的提示，再试试用管理员账号强制推送，看会不会被拒绝，这样才能确保权限真的生效了。
迁移后发现部分历史提交记录丢失，可能是什么原因？
最常见的原因是未使用镜像克隆（git clone mirror）。普通git clone只会拉取默认分支的最新提交，而镜像克隆能完整复制所有分支、标签和隐藏引用。 推送过程中断（如网络断开）也可能导致部分数据未传输成功。解决方法：重新用git clone mirror拉取GitHub仓库，删除GitLab上的不完整仓库，然后重新执行git push mirror origin。
GitHub仓库包含子模块（submodule），迁移时需要特别注意什么？
子模块需单独处理，否则迁移后会因链接指向GitHub旧地址导致依赖报错。正确步骤：①迁移主仓库前，先用git submodule status列出所有子模块；②逐个对子模块执行镜像克隆和推送（流程与主仓库相同）；③主仓库迁移完成后，进入本地镜像仓库，用git submodule foreach 'git remote set-url origin 新子模块GitLab地址'批量更新子模块的远程链接，再推送更新后的配置。
GitHub和GitLab的分支保护规则有差异，迁移后如何确保权限一致？
两者的分支保护功能不完全互通，需手动对照配置。例如GitHub的“Require pull request reviews before merging”对应GitLab的“Merge request approvals”，但GitLab支持更细粒度的“合并检查”（如要求通过特定CI任务）。 迁移前截图GitHub的分支保护页面（包括审核人数、CI检查规则、强制推送限制等），在GitLab的“Settings→Repository→Protected branches”中逐项重建，完成后用测试账号尝试合并分支，验证规则是否生效。
迁移一个5GB左右的仓库大概需要多长时间？影响迁移速度的因素有哪些？
通常需要30分钟到2小时，具体取决于三个因素：①网络速度（ 使用企业网络或有线连接，Wi-Fi可能因波动中断）；②仓库大小（包含大文件或LFS对象会增加传输时间，可提前用git lfs migrate优化）；③GitLab服务器负载（避开GitLab高峰期，如工作日9:00-11:00）。去年迁移一个6GB的游戏项目时，因包含大量美术资源，在凌晨2点迁移仅用了45分钟，而白天尝试时耗时近2小时。
迁移过程中突然中断（如网络断开），如何判断是否需要重新迁移？
先检查GitLab仓库的“Commits”页面，对比提交总数与GitHub是否一致；再用git fetch origin拉取GitLab远程仓库，执行git log graph all查看分支结构是否完整。若提交数缺失或分支不完整，需重新迁移：删除GitLab上的仓库（避免残留数据冲突），重新执行镜像克隆和推送。若仅部分标签或小分支未推送，可单独用git push origin 标签名或git push origin 分支名补充推送。
