做开发这些年，我几乎每隔一段时间就会遇到同一个诉求：把 GitHub 上的某个开源项目完整搬到公司内部的 GitLab 服务器上。原因不外乎几种——内网环境访问外网不稳定、团队统一代码托管平台要求所有仓库都收敛到 GitLab、或者项目敏感度较高不适合放在公网。很多第一次做迁移的同学上来就问：“有没有不用写一堆脚本、不用搭同步服务，就能把 GitHub 项目克隆到本地 GitLab 的办法？”答案是可以的，而且路子不止一条。这篇博文我就把手头验证过的“零代码迁移”完整方案拆开讲清楚，同时把命令行克隆这个备选方案一并讲透，保证你看完能直接上手操作。这篇内容适合谁看：维护内部代码平台的运维同学、需要定期搬运开源项目的研发人员，以及在公司合规要求下必须把公网仓库同步到内网 GitLab 的团队。你不需要提前精通 Git 原理，我会把操作步骤、参数含义、踩坑点全部摊开来说。整套流程里最关键的一个认知是：GitHub 到 GitLab 的迁移本质上就是“拉一份完整镜像 + 推送到新地址”，中间不需要写任何代码，充分利用 Git 和 GitLab 自带能力就够了。1. 项目场景与核心思路拆解1.1 为什么要把 GitHub 仓库搬到本地 GitLab先说场景。多数团队自建 GitLab 的核心动机是代码不外流，或者希望把所有仓库统一收口到一套权限体系里。GitHub 上优秀的开源库太多，研发人员随手 clone 下来做二次开发很常见，但如果只停留在本地，代码就散落在各人电脑上，版本管理、权限控制、备份都成了问题。于是“把 GitHub 上的项目作为起点，在 GitLab 建立对应的仓库”就成了一个标准操作。这个迁移行为背后有几个现实需求：一是内网开发需要稳定的代码源；二是评审流程需要被统一到 GitLab 的 MR 机制里；三是从公网仓库 fork 下来后，团队需要持续跟踪上游更新。第三点特别容易被人忽略，很多人做完一次性导入就以为结束了，等到上游发了新版本才发现本地仓库还停在几个月前。所以我在后面专门用一节讲增量更新的做法。1.2 “零代码导入”到底怎么实现所谓“零代码”，不是说你不用碰 Git，而是不需要你手写迁移脚本、不需要搭 Jenkins 任务、不需要用 API 写复杂的批量处理。GitLab 本身内置了“导入项目”功能，支持从 GitHub 直接拉仓库，你只需要在网页上填几个参数、粘贴一个 Token，剩下的分支、标签、提交历史、MR（合并请求）全部由 GitLab 后台自动完成。这条路最适合绝大多数普通使用者。如果你负责的 GitLab 版本比较旧，或者出于安全限制不能直接访问 GitHub，那还有另一条零代码思路：在本地执行 Git 命令，把 GitHub 仓库拉下来，再把本地仓库“远程地址”改成 GitLab 地址推送上去。这同样不需要写代码，几行命令就完成了。两条路我会都写清楚，方便你根据自己环境选择。1.3 方案选型：UI 导入和命令行克隆各适合谁先给结论：能用 GitLab 网页导入就用网页导入，操作成本最低，还自动把 issue、MR、看板这类项目元数据一并带过来。它适合仓库数量少（个位数到十几个）、GitLab 能访问到 GitHub 的网络环境。命令行克隆更适合这些情况：GitLab 与 GitHub 之间网络不通，或者管理员出于安全考虑关闭了导入功能，再或者你要迁移的仓库体积很大，网页导入总是超时。命令行方式对网络的要求更灵活——你可以选在任意一台能同时访问两端网络的机器上操作，甚至先手动下载压缩包再离线推送。缺点是只会迁移 Git 仓库本身，不会带走 issues 和 MR。平时我给自己维护的镜像仓库做同步时，也是优先用命令行方式，因为可以写进 crontab 做周期同步，后面会细说。2. 动手前需要确认的准备工作2.1 确认两端账号与必要权限开始迁移前，先把两边账号的权限摸清楚，避免操作到一半才发现没权限。GitHub 方你需要的是目标仓库的读权限，如果仓库是公开的，匿名访问就足够，不需要任何特殊权限。要迁移私有仓库的话，就得用到 Personal Access Token（PAT），这个 Token 的权限至少勾选repo范围。生成路径在 GitHub 的 Settings -> Developer settings -> Personal access tokens -> Tokens (classic)，生成后立即复制保存，因为页面关掉就再也看不到了。GitLab 方你需要的是目标 Group（组）的 Owner 或 Maintainer 权限，因为导入操作本质是在这个组下创建新项目。另外如果 GitLab 是私有部署且开启了“仅允许管理员导入”，那你还要找管理员开权限，否则网页上根本看不到导入入口。这个卡点很多人第一次碰到，提前确认能省不少沟通时间。2.2 网络连通性与域名可访问性检查网页导入方式要求你的 GitLab 服务器能够直接访问 GitHub。但很多公司内网 GitLab 在隔离网段，外网访问走代理或者干脆不通。验证方法很简单：在一台能访问 GitLab 管理后台的机器上，从 GitLab 服务器（或者你本机）执行：curl -I https://github.com如果在 GitLab 服务器上能正常返回 HTTP 状态码，说明网络层面没问题。如果返回超时或者连接被拒绝，就要考虑命令行的替代方案。命令行方案对网络的要求比较宽松，因为执行命令的机器只要“能访问 GitHub”同时又“能访问 GitLab”即可。很多同事的办公电脑恰好满足这两个条件，这就够了。如果办公电脑也不通 GitHub，那就需要让网络管理员开放相关域名访问，或者找一台跳板机来操作。2.3 Git 客户端版本与全局配置检查命令行方案里 Git 客户端版本会影响部分参数行为，建议至少使用 2.x 版本。在终端执行：git --version如果版本过低，走 HTTPS 协议推送大仓库时容易遇到未知错误。另外检查一下全局用户配置：git config --global user.name git config --global user.email这两个配置会在你执行 commit 时写入提交信息。迁移场景虽然不会新增提交，但后续如果你在本地改了代码再推送，缺了用户名和邮箱会导致提交失败。3. 零代码操作：GitLab 网页导入 GitHub 项目3.1 第一步：获取 GitHub Personal Access Token网页导入的核心凭证就是 GitHub 的 PAT。这个 Token 相当于你把 GitHub 账号的一部分操作权限临时授权给 GitLab，GitLab 用它在后台替你拉取仓库内容。创建步骤我再说细致一点：GitHub 右上角头像 -> Settings。左侧菜单拉到最底部，进入 Developer settings。选择 Personal access tokens -> Tokens (classic)。点击 Generate new token，填写名称（建议写成gitlab-import便于识别），过期时间按需设置。在 Select scopes 里勾选repo（完整控制私有仓库）和read:org（如果仓库在组织下会用到）。点击生成，复制 Token 并妥善保存。注意 Token 不要提交到任何 Git 仓库里，也不要贴在即时通讯群里。它代表了你的账号权限，泄露后别人可以拿它读取你的私有仓库。实操中我习惯把 Token 放到本机密码管理器里，随用随取。3.2 第二步：在 GitLab 中发起导入用管理员或项目组 Owner 账号登录 GitLab，创建新项目的路径有两个：方式一是导航栏直接点“新建项目”，GitLab 会展示三种创建方式：创建空白项目、从模板创建、导入项目。选择“导入项目”。方式二是如果之前已经进入某个 Group，点击该 Group 页面里的“新建项目”，同样会出现导入选项。导入后项目会默认归入当前 Group，权限体系自动沿用 Group 的设置，这通常正是团队想要的。选择“GitHub”作为导入源后，GitLab 会要求你粘贴刚才创建的 GitHub PAT。粘贴后点连接，GitLab 会调用 GitHub API 拉取你有权访问的仓库列表。如果提示连接失败，优先检查 Token 权限和网络连通性。3.3 第三步：选择合适的仓库和目标路径连接成功后，页面会列出一堆 GitHub 仓库，每个仓库右侧有“导入”按钮。你可以单个导入，也可以勾选多个仓库批量导入。批量导入对团队初始化特别方便，一次能把过去分散在 GitHub 下的所有项目统一搬到 GitLab。这里有个细节值得注意：GitLab 默认会把 GitHub 仓库名原样带过来，如果目标 Group 下已经存在同名项目，导入会失败或提示重名。GitLab 提供了重命名选项，英文界面字段是 “Rename”。我建议迁移前先梳理一遍目标组下已有项目和 GitHub 仓库名称的冲突情况，省得导入到一半才发现撞名。导入过程中，GitLab 后台会异步执行，页面显示导入进度。仓库越大耗时越长，但不需要你一直守着页面。我习惯同时打开 GitLab 的“项目活动”页面观察是否推送成功。批量导入时如果有某个仓库失败，可以单独重试，不影响其他仓库。3.4 导入选项的细节与导入后的检查项GitLab 导入 GitHub 项目时，默认会迁移：Git 仓库的完整历史（所有提交记录）、分支、标签、合并请求（MR）、Issues、评论、Wiki。这是一个很完整的项目级迁移，比单纯搬运代码要划算得多。导入完成后，我强烈建议做一轮检查，别急着通知团队：检查分支保护规则。GitHub 上默认分支（通常是 main）到了 GitLab 不一定自动开启保护，需要到 Settings -> Repository -> Protected branches 里手动配置，否则团队成员可以直接往主分支推代码。检查 CI/CD 变量。如果项目在 GitHub 上用 Actions，迁移到 GitLab 后这些配置不会自动变成 GitLab CI/CD 配置，需要手动编写.gitlab-ci.yml，数据库密码、密钥这类 CI 变量要在 GitLab 里重新录入。检查成员权限。GitHub 仓库的协作者不会自动映射为 GitLab 项目成员，需要重新在 GitLab 里添加成员并分配角色。检查大文件引用。如果原仓库使用了 Git LFS，确认 GitLab 服务端已开启 LFS 支持，否则大文件虽然能推上来，但无法正常检出。这些检查项看着琐碎，但都是真实的“迁移后翻车点”。我给一个内部团队做过一次批量导入，当时有三四个项目都因为主分支没开保护、成员没迁移导致后续协作出问题，后来专门补了一道检查流程才消停。4. 命令行方案：一条命令克隆并推送到 GitLab4.1 为什么网页导入这么好用，我还要讲命令行因为现实环境永远不是理想状态。我见过不少 GitLab 部署在纯内网、无法直连 GitHub 的情况，这时候网页导入根本用不了；也遇到过仓库里历史提交非常多、网页导入跑到一半超时的场景。命令行克隆的价值在于它把“拉取”和“推送”两个动作拆开了，中间可以人工干预、断点重试、甚至可以离线转移，灵活性远高于 UI 导入。另外命令行方案还能用于持续同步：GitHub 上游仓库更新后，你想把新提交镜像到本地 GitLab，不需要重新导入一遍，几条增量命令就能搞定。这功能网页导入可做不到。所以命令行方案不是一个“备用方案”，它更准确的说法是“进阶维护方案”。4.2 标准操作流程：裸克隆加推送首次迁移我用的是“裸克隆 + 推送”的组合，流程很简单：git clone --bare https://github.com/某团队/某项目.git cd 某项目.git git push --mirror http://gitlab.example.com/某组/某项目.git三条命令完成整套首次迁移。--bare参数表示克隆一个“裸仓库”，这个仓库没有工作目录，只包含.git目录里的内容，也就是完整的 Git 元数据：所有分支、所有提交、所有标签。之所以用裸仓库，是因为我们只需要搬家，不需要在本地修改代码，裸仓库最干净。第二条命令是进入裸仓库目录。第三条命令用--mirror参数推送到 GitLab 新仓库地址。--mirror的作用是让远端仓库和本地仓库保持完全一致：它会把本地所有分支、标签都推上去，同时把远端已有的、但本地已经不存在的分支删除掉。对于“把 GitHub 仓库完整变成 GitLab 仓库”这个目标，--mirror是最合适的参数。需要提前在 GitLab 上创建好空项目吗？两种做法都行。先到 GitLab 页面创建一个空项目，然后拿到项目地址用于推送，这是最常见的方式，好处是地址一眼可见、不会推错地方。如果你对 GitLab API 熟悉，也可以用命令行创建项目，但对大多数人来说网页点几下更快，没必要追求全命令行。4.3 裸克隆、镜像推送与普通克隆的区别很多同学分不清git clone --bare和普通git clone，我解释一下。普通git clone下来的仓库包含两个部分：一份当前工作区的文件快照（checkout 出来的内容），加上隐藏的.git目录。工作区里的文件是给人看的、可以修改的。而裸克隆只保留.git部分，没有工作区，整个目录结构就是一套 Git 元数据。用生活类比来说：普通克隆是把一本书复印了一份，你可以在复印件上写字；裸克隆是把这本书的原稿母版直接拿走，完全不分页展示给你，但所有出版信息一字不少。在迁移场景里，我们用裸仓库推送有几个好处：体积更小，因为它不会重复存放当前分支的文件快照。不会因为当前工作区状态导致推送失败。包含了所有远端分支，而普通克隆默认只克隆所有分支的引用到本地，但只检出默认分支。如果你的默认分支不是 main 而是 release，普通克隆后推送可能会漏掉分支。--mirror推送时会自动把 GitHub 上的仓库描述、配置等一并复制到 GitLab 新仓库，保持仓库设置的一致性。4.4 本地同步上游更新到 GitLab 的增量流程这是命令行方案里我个人最常用的功能。项目迁移完成后，GitHub 上游又发布了新版本，怎么做增量同步？很多人第一反应是删了重建，这明显不对。正确流程如下：git clone --bare https://github.com/某团队/某项目.git cd 某项目.git git remote set-url --push origin http://gitlab.example.com/某组/某项目.git git fetch --all git push --mirror origin第三条命令git remote set-url --push的作用是修改 push 的远程地址，但保留 fetch 的地址仍指向 GitHub。这样本地裸仓库既是 GitHub 的镜像，又是 GitLab 的上游源。执行git fetch --all会把 GitHub 上的新提交拉下来，再git push --mirror origin推送到 GitLab。这套流程后面完全可以做成一个定时任务。Linux 系统下可以写成 shell 脚本塞进 crontab，Windows 下可以用计划任务调用脚本。脚本内容无非就是把上面几条命令按顺序执行，加上日志输出。我实际跑下来，一个几十 MB 的仓库增量同步往往几秒完成，对服务器几乎没有压力。如果你管理着一批镜像仓库，这个方法能省下大量人工操作。注意：--mirror推送会把远端仓库强制变为本地仓库的状态。如果在 GitLab 上有人直接改了代码（没通过本地裸仓库），下一次git push --mirror会把这个改动覆盖掉。所以镜像仓库要约定好：GitLab 上的项目只读，所有修改都从 GitHub 上游同步，否则就别用 mirror 方式，改用git push --all && git push --tags。5. 常见问题与排查技巧实录5.1 认证一直失败怎么办网页导入时最常见的问题是连不上 GitHub，或者 Token 验证不通过。排查顺序是先确认网络，再确认 Token。网络层面用curl -I https://github.com测试，如果 GitLab 服务器返回不了 HTTP 响应，那就是网络隔离问题，没有别的办法，只能走命令行方案或者申请网络策略。Token 层面先确认权限范围有没有勾选 repo，再确认 Token 有没有过期，最后确认仓库是不是在你 Token 有权访问的账号或组织下。命令行推送时认证失败同样高频。推送到 GitLab 用 HTTPS 地址时，通常提示输入用户名和密码，但 GitLab 从某个版本开始不再接受账号密码直接推送，必须用 Personal Access Token 作为密码。具体操作：用户名填写 GitLab 用户名，密码栏粘贴你在 GitLab 生成的 PAT，而不是登录密码。很多人栽在这一步，一直输自己的 GitLab 登录密码，怎么试都报错。如果你不想每次推送都手动输入，可以在本地保存凭证：git config --global credential.helper store这个命令会把凭证明文存到~/.git-credentials，安全性一般，个人开发机可以接受，团队公用的机器不建议这么干，建议改用manager-core这类更安全的凭证管理器。5.2 仓库太大导致导入或推送超时Git 仓库体积大通常有两个原因：历史中包含大量二进制文件，或者长期积累了大量提交记录。网页导入对这种仓库非常不友好，后台任务跑几十分钟后容易卡死或报超时。命令行方案相对稳妥，但推送时也可能因为数据量太大、单次 HTTP 请求受限而失败。处理思路有两个。一是把一次大推送拆成多次小推送，先把所有分支推到 GitLab，再单独推标签：git push origin --all git push origin --tags二是调整 Git 的 HTTP 缓冲区大小。走 HTTPS 协议推送大对象时，可以临时加大缓冲区：git config --global http.postBuffer 524288000这个值单位是字节，上面的例子是 500MB。实测很多不明原因的推送中断，把缓冲区调大之后就好了。如果是走 SSH 协议，则不太会遇到这类 HTTP 缓冲区问题。所以我的建议是：gitlab 地址支持 SSH 的话，优先配置 SSH Key，体验会顺滑很多。如果你遇到的是 GitLab 上传文件大小限制，那问题在服务端配置。GitLab 默认有git max file size限制，需要管理员在管理后台或者配置文件中调大，这个改动要重启服务才能生效，最好提前和运维沟通好。5.3 子模块和 LFS 文件如何处理GitHub 仓库里如果用了 submodule（子模块），直接git clone --bare只会拉取子模块的引用记录，不会拉取子模块本身的内容。镜像推送到 GitLab 后，别人 clone 这个项目时会看到子模块目录是空的。处理办法是在裸克隆前先初始化子模块：git clone --recurse-submodules https://github.com/某团队/某项目.git这个命令会连同子模块一起克隆下来。之后推送时，普通git push --all并不会把子模块的内容推送到 GitLab，因为子模块本身就是独立的 Git 仓库，它们的 remote 地址还指向原始 GitHub 地址。所以你还需要单独把每个子模块也镜像到 GitLab，并修改父项目里的.gitmodules文件指向新的子模块地址，再提交这个修改。LFS（Large File Storage）则是另一个常见坑。GitHub 仓库启用了 LFS 后，远程仓库里存的是文件的指针，实际大文件存放在 GitHub LFS 存储服务上。裸克隆时，如果没装git-lfs插件，克隆下来的只是指针文件。装插件后有两条路：让本地裸仓库初始化 LFS 并拉取大文件内容，或者干脆在推送后让 GitLab 端也启用 LFS，再重新 clone 触发大文件下载。实际迁移时我通常先检查仓库里是否用了 LFS：git lfs ls-files如果输出为空说明没用 LFS，省心。如果列出了文件，那迁移后千万记得测试一下大文件能否正常检出，否则团队实际用起来才发现文件损坏，那就被动了。5.4 权限、合规与团队协作的收尾建议仓库迁移到 GitLab 只是完成了“搬东西”这一步，真正让团队顺利用起来还需要收尾。我在多个迁移项目里总结了一套固定动作：确认默认分支设置。GitLab 新建项目默认分支是 main，如果 GitHub 原仓库用 master，迁移后要在 GitLab 项目设置里调整默认分支，否则 MR 的 Target 分支容易选错。配置分支保护。至少把 main/master 分支设为“仅允许 Maintainer 推送”，维持和 GitHub 上一致的保护策略。清理 GitHub 侧的敏感历史。如果仓库包含密钥、数据库密码等敏感内容，直接迁移是危险行为，应该先处理历史提交中的敏感信息再导入。这个要重点提示，迁移动作本身不能成为数据泄露的通道。保留 GitHub 旧仓库一段时间。迁移完成后先别删 GitHub 上的原仓库，保留一到两个月作为回退方案。团队在 GitLab 上稳定运行后再决定去留。写一份简短的迁移说明文档。告诉团队新仓库地址、同步策略、分支规范、CI 状态，让所有人知道工作流切换到了哪里。6. 聊聊我实际跑迁移后的一些心得体会用 GitLab 网页导入给团队做过一次二十多个仓库的批量迁移，全程零代码，网页点按钮加审核权限就完成了大半。也碰到过一个大型仓库，网页导入反复失败，最后在办公室一台能通外网的机器上用裸克隆加推送十五分钟搞定。两种方案不是谁替代谁的关系，而是互补的。从经验角度看，有几个容易被忽略的细节值得多说一句。第一，Token 权限宁多勿少但用后即焚，迁移完把 GitHub PAT 删掉能从源头上防止泄露。第二，GitLab 导入完成后，先让一两个同事实际 clone 和 push 一轮再通知全员切流，比盲目广播“迁移完成”稳妥得多。第三，镜像同步脚本要加日志和失败告警，否则定时任务静默失败，过几天才发现本地 GitLab 落后上游好几个版本，丢失了关键更新。如果你要迁移的仓库数量在几十个以上，可以考虑用 GitLab 的批量导入脚本或者 API 做进一步自动化，但那已经是“有代码”的路线了。对于日常零星同步，网页导入配合命令行增量更新，已经能覆盖绝大多数场景。希望这篇内容能帮你少走一段弯路。
做开发这些年，我几乎每隔一段时间就会遇到同一个诉求：把 GitHub 上的某个开源项目完整搬到公司内部的 GitLab 服务器上。原因不外乎几种——内网环境访问外网不稳定、团队统一代码托管平台要求所有仓库都收敛到 GitLab、或者项目敏感度较高不适合放在公网。很多第一次做迁移的同学上来就问：“有没有不用写一堆脚本、不用搭同步服务，就能把 GitHub 项目克隆到本地 GitLab 的办法？”答案是可以的，而且路子不止一条。这篇博文我就把手头验证过的“零代码迁移”完整方案拆开讲清楚，同时把命令行克隆这个备选方案一并讲透，保证你看完能直接上手操作。这篇内容适合谁看：维护内部代码平台的运维同学、需要定期搬运开源项目的研发人员，以及在公司合规要求下必须把公网仓库同步到内网 GitLab 的团队。你不需要提前精通 Git 原理，我会把操作步骤、参数含义、踩坑点全部摊开来说。整套流程里最关键的一个认知是：GitHub 到 GitLab 的迁移本质上就是“拉一份完整镜像 + 推送到新地址”，中间不需要写任何代码，充分利用 Git 和 GitLab 自带能力就够了。1. 项目场景与核心思路拆解1.1 为什么要把 GitHub 仓库搬到本地 GitLab先说场景。多数团队自建 GitLab 的核心动机是代码不外流，或者希望把所有仓库统一收口到一套权限体系里。GitHub 上优秀的开源库太多，研发人员随手 clone 下来做二次开发很常见，但如果只停留在本地，代码就散落在各人电脑上，版本管理、权限控制、备份都成了问题。于是“把 GitHub 上的项目作为起点，在 GitLab 建立对应的仓库”就成了一个标准操作。这个迁移行为背后有几个现实需求：一是内网开发需要稳定的代码源；二是评审流程需要被统一到 GitLab 的 MR 机制里；三是从公网仓库 fork 下来后，团队需要持续跟踪上游更新。第三点特别容易被人忽略，很多人做完一次性导入就以为结束了，等到上游发了新版本才发现本地仓库还停在几个月前。所以我在后面专门用一节讲增量更新的做法。1.2 “零代码导入”到底怎么实现所谓“零代码”，不是说你不用碰 Git，而是不需要你手写迁移脚本、不需要搭 Jenkins 任务、不需要用 API 写复杂的批量处理。GitLab 本身内置了“导入项目”功能，支持从 GitHub 直接拉仓库，你只需要在网页上填几个参数、粘贴一个 Token，剩下的分支、标签、提交历史、MR（合并请求）全部由 GitLab 后台自动完成。这条路最适合绝大多数普通使用者。如果你负责的 GitLab 版本比较旧，或者出于安全限制不能直接访问 GitHub，那还有另一条零代码思路：在本地执行 Git 命令，把 GitHub 仓库拉下来，再把本地仓库“远程地址”改成 GitLab 地址推送上去。这同样不需要写代码，几行命令就完成了。两条路我会都写清楚，方便你根据自己环境选择。1.3 方案选型：UI 导入和命令行克隆各适合谁先给结论：能用 GitLab 网页导入就用网页导入，操作成本最低，还自动把 issue、MR、看板这类项目元数据一并带过来。它适合仓库数量少（个位数到十几个）、GitLab 能访问到 GitHub 的网络环境。命令行克隆更适合这些情况：GitLab 与 GitHub 之间网络不通，或者管理员出于安全考虑关闭了导入功能，再或者你要迁移的仓库体积很大，网页导入总是超时。命令行方式对网络的要求更灵活——你可以选在任意一台能同时访问两端网络的机器上操作，甚至先手动下载压缩包再离线推送。缺点是只会迁移 Git 仓库本身，不会带走 issues 和 MR。平时我给自己维护的镜像仓库做同步时，也是优先用命令行方式，因为可以写进 crontab 做周期同步，后面会细说。2. 动手前需要确认的准备工作2.1 确认两端账号与必要权限开始迁移前，先把两边账号的权限摸清楚，避免操作到一半才发现没权限。GitHub 方你需要的是目标仓库的读权限，如果仓库是公开的，匿名访问就足够，不需要任何特殊权限。要迁移私有仓库的话，就得用到 Personal Access Token（PAT），这个 Token 的权限至少勾选repo范围。生成路径在 GitHub 的 Settings -> Developer settings -> Personal access tokens -> Tokens (classic)，生成后立即复制保存，因为页面关掉就再也看不到了。GitLab 方你需要的是目标 Group（组）的 Owner 或 Maintainer 权限，因为导入操作本质是在这个组下创建新项目。另外如果 GitLab 是私有部署且开启了“仅允许管理员导入”，那你还要找管理员开权限，否则网页上根本看不到导入入口。这个卡点很多人第一次碰到，提前确认能省不少沟通时间。2.2 网络连通性与域名可访问性检查网页导入方式要求你的 GitLab 服务器能够直接访问 GitHub。但很多公司内网 GitLab 在隔离网段，外网访问走代理或者干脆不通。验证方法很简单：在一台能访问 GitLab 管理后台的机器上，从 GitLab 服务器（或者你本机）执行：curl -I https://github.com如果在 GitLab 服务器上能正常返回 HTTP 状态码，说明网络层面没问题。如果返回超时或者连接被拒绝，就要考虑命令行的替代方案。命令行方案对网络的要求比较宽松，因为执行命令的机器只要“能访问 GitHub”同时又“能访问 GitLab”即可。很多同事的办公电脑恰好满足这两个条件，这就够了。如果办公电脑也不通 GitHub，那就需要让网络管理员开放相关域名访问，或者找一台跳板机来操作。2.3 Git 客户端版本与全局配置检查命令行方案里 Git 客户端版本会影响部分参数行为，建议至少使用 2.x 版本。在终端执行：git --version如果版本过低，走 HTTPS 协议推送大仓库时容易遇到未知错误。另外检查一下全局用户配置：git config --global user.name git config --global user.email这两个配置会在你执行 commit 时写入提交信息。迁移场景虽然不会新增提交，但后续如果你在本地改了代码再推送，缺了用户名和邮箱会导致提交失败。3. 零代码操作：GitLab 网页导入 GitHub 项目3.1 第一步：获取 GitHub Personal Access Token网页导入的核心凭证就是 GitHub 的 PAT。这个 Token 相当于你把 GitHub 账号的一部分操作权限临时授权给 GitLab，GitLab 用它在后台替你拉取仓库内容。创建步骤我再说细致一点：GitHub 右上角头像 -> Settings。左侧菜单拉到最底部，进入 Developer settings。选择 Personal access tokens -> Tokens (classic)。点击 Generate new token，填写名称（建议写成gitlab-import便于识别），过期时间按需设置。在 Select scopes 里勾选repo（完整控制私有仓库）和read:org（如果仓库在组织下会用到）。点击生成，复制 Token 并妥善保存。注意 Token 不要提交到任何 Git 仓库里，也不要贴在即时通讯群里。它代表了你的账号权限，泄露后别人可以拿它读取你的私有仓库。实操中我习惯把 Token 放到本机密码管理器里，随用随取。3.2 第二步：在 GitLab 中发起导入用管理员或项目组 Owner 账号登录 GitLab，创建新项目的路径有两个：方式一是导航栏直接点“新建项目”，GitLab 会展示三种创建方式：创建空白项目、从模板创建、导入项目。选择“导入项目”。方式二是如果之前已经进入某个 Group，点击该 Group 页面里的“新建项目”，同样会出现导入选项。导入后项目会默认归入当前 Group，权限体系自动沿用 Group 的设置，这通常正是团队想要的。选择“GitHub”作为导入源后，GitLab 会要求你粘贴刚才创建的 GitHub PAT。粘贴后点连接，GitLab 会调用 GitHub API 拉取你有权访问的仓库列表。如果提示连接失败，优先检查 Token 权限和网络连通性。3.3 第三步：选择合适的仓库和目标路径连接成功后，页面会列出一堆 GitHub 仓库，每个仓库右侧有“导入”按钮。你可以单个导入，也可以勾选多个仓库批量导入。批量导入对团队初始化特别方便，一次能把过去分散在 GitHub 下的所有项目统一搬到 GitLab。这里有个细节值得注意：GitLab 默认会把 GitHub 仓库名原样带过来，如果目标 Group 下已经存在同名项目，导入会失败或提示重名。GitLab 提供了重命名选项，英文界面字段是 “Rename”。我建议迁移前先梳理一遍目标组下已有项目和 GitHub 仓库名称的冲突情况，省得导入到一半才发现撞名。导入过程中，GitLab 后台会异步执行，页面显示导入进度。仓库越大耗时越长，但不需要你一直守着页面。我习惯同时打开 GitLab 的“项目活动”页面观察是否推送成功。批量导入时如果有某个仓库失败，可以单独重试，不影响其他仓库。3.4 导入选项的细节与导入后的检查项GitLab 导入 GitHub 项目时，默认会迁移：Git 仓库的完整历史（所有提交记录）、分支、标签、合并请求（MR）、Issues、评论、Wiki。这是一个很完整的项目级迁移，比单纯搬运代码要划算得多。导入完成后，我强烈建议做一轮检查，别急着通知团队：检查分支保护规则。GitHub 上默认分支（通常是 main）到了 GitLab 不一定自动开启保护，需要到 Settings -> Repository -> Protected branches 里手动配置，否则团队成员可以直接往主分支推代码。检查 CI/CD 变量。如果项目在 GitHub 上用 Actions，迁移到 GitLab 后这些配置不会自动变成 GitLab CI/CD 配置，需要手动编写.gitlab-ci.yml，数据库密码、密钥这类 CI 变量要在 GitLab 里重新录入。检查成员权限。GitHub 仓库的协作者不会自动映射为 GitLab 项目成员，需要重新在 GitLab 里添加成员并分配角色。检查大文件引用。如果原仓库使用了 Git LFS，确认 GitLab 服务端已开启 LFS 支持，否则大文件虽然能推上来，但无法正常检出。这些检查项看着琐碎，但都是真实的“迁移后翻车点”。我给一个内部团队做过一次批量导入，当时有三四个项目都因为主分支没开保护、成员没迁移导致后续协作出问题，后来专门补了一道检查流程才消停。4. 命令行方案：一条命令克隆并推送到 GitLab4.1 为什么网页导入这么好用，我还要讲命令行因为现实环境永远不是理想状态。我见过不少 GitLab 部署在纯内网、无法直连 GitHub 的情况，这时候网页导入根本用不了；也遇到过仓库里历史提交非常多、网页导入跑到一半超时的场景。命令行克隆的价值在于它把“拉取”和“推送”两个动作拆开了，中间可以人工干预、断点重试、甚至可以离线转移，灵活性远高于 UI 导入。另外命令行方案还能用于持续同步：GitHub 上游仓库更新后，你想把新提交镜像到本地 GitLab，不需要重新导入一遍，几条增量命令就能搞定。这功能网页导入可做不到。所以命令行方案不是一个“备用方案”，它更准确的说法是“进阶维护方案”。4.2 标准操作流程：裸克隆加推送首次迁移我用的是“裸克隆 + 推送”的组合，流程很简单：git clone --bare https://github.com/某团队/某项目.git cd 某项目.git git push --mirror http://gitlab.example.com/某组/某项目.git三条命令完成整套首次迁移。--bare参数表示克隆一个“裸仓库”，这个仓库没有工作目录，只包含.git目录里的内容，也就是完整的 Git 元数据：所有分支、所有提交、所有标签。之所以用裸仓库，是因为我们只需要搬家，不需要在本地修改代码，裸仓库最干净。第二条命令是进入裸仓库目录。第三条命令用--mirror参数推送到 GitLab 新仓库地址。--mirror的作用是让远端仓库和本地仓库保持完全一致：它会把本地所有分支、标签都推上去，同时把远端已有的、但本地已经不存在的分支删除掉。对于“把 GitHub 仓库完整变成 GitLab 仓库”这个目标，--mirror是最合适的参数。需要提前在 GitLab 上创建好空项目吗？两种做法都行。先到 GitLab 页面创建一个空项目，然后拿到项目地址用于推送，这是最常见的方式，好处是地址一眼可见、不会推错地方。如果你对 GitLab API 熟悉，也可以用命令行创建项目，但对大多数人来说网页点几下更快，没必要追求全命令行。4.3 裸克隆、镜像推送与普通克隆的区别很多同学分不清git clone --bare和普通git clone，我解释一下。普通git clone下来的仓库包含两个部分：一份当前工作区的文件快照（checkout 出来的内容），加上隐藏的.git目录。工作区里的文件是给人看的、可以修改的。而裸克隆只保留.git部分，没有工作区，整个目录结构就是一套 Git 元数据。用生活类比来说：普通克隆是把一本书复印了一份，你可以在复印件上写字；裸克隆是把这本书的原稿母版直接拿走，完全不分页展示给你，但所有出版信息一字不少。在迁移场景里，我们用裸仓库推送有几个好处：体积更小，因为它不会重复存放当前分支的文件快照。不会因为当前工作区状态导致推送失败。包含了所有远端分支，而普通克隆默认只克隆所有分支的引用到本地，但只检出默认分支。如果你的默认分支不是 main 而是 release，普通克隆后推送可能会漏掉分支。--mirror推送时会自动把 GitHub 上的仓库描述、配置等一并复制到 GitLab 新仓库，保持仓库设置的一致性。4.4 本地同步上游更新到 GitLab 的增量流程这是命令行方案里我个人最常用的功能。项目迁移完成后，GitHub 上游又发布了新版本，怎么做增量同步？很多人第一反应是删了重建，这明显不对。正确流程如下：git clone --bare https://github.com/某团队/某项目.git cd 某项目.git git remote set-url --push origin http://gitlab.example.com/某组/某项目.git git fetch --all git push --mirror origin第三条命令git remote set-url --push的作用是修改 push 的远程地址，但保留 fetch 的地址仍指向 GitHub。这样本地裸仓库既是 GitHub 的镜像，又是 GitLab 的上游源。执行git fetch --all会把 GitHub 上的新提交拉下来，再git push --mirror origin推送到 GitLab。这套流程后面完全可以做成一个定时任务。Linux 系统下可以写成 shell 脚本塞进 crontab，Windows 下可以用计划任务调用脚本。脚本内容无非就是把上面几条命令按顺序执行，加上日志输出。我实际跑下来，一个几十 MB 的仓库增量同步往往几秒完成，对服务器几乎没有压力。如果你管理着一批镜像仓库，这个方法能省下大量人工操作。注意：--mirror推送会把远端仓库强制变为本地仓库的状态。如果在 GitLab 上有人直接改了代码（没通过本地裸仓库），下一次git push --mirror会把这个改动覆盖掉。所以镜像仓库要约定好：GitLab 上的项目只读，所有修改都从 GitHub 上游同步，否则就别用 mirror 方式，改用git push --all && git push --tags。5. 常见问题与排查技巧实录5.1 认证一直失败怎么办网页导入时最常见的问题是连不上 GitHub，或者 Token 验证不通过。排查顺序是先确认网络，再确认 Token。网络层面用curl -I https://github.com测试，如果 GitLab 服务器返回不了 HTTP 响应，那就是网络隔离问题，没有别的办法，只能走命令行方案或者申请网络策略。Token 层面先确认权限范围有没有勾选 repo，再确认 Token 有没有过期，最后确认仓库是不是在你 Token 有权访问的账号或组织下。命令行推送时认证失败同样高频。推送到 GitLab 用 HTTPS 地址时，通常提示输入用户名和密码，但 GitLab 从某个版本开始不再接受账号密码直接推送，必须用 Personal Access Token 作为密码。具体操作：用户名填写 GitLab 用户名，密码栏粘贴你在 GitLab 生成的 PAT，而不是登录密码。很多人栽在这一步，一直输自己的 GitLab 登录密码，怎么试都报错。如果你不想每次推送都手动输入，可以在本地保存凭证：git config --global credential.helper store这个命令会把凭证明文存到~/.git-credentials，安全性一般，个人开发机可以接受，团队公用的机器不建议这么干，建议改用manager-core这类更安全的凭证管理器。5.2 仓库太大导致导入或推送超时Git 仓库体积大通常有两个原因：历史中包含大量二进制文件，或者长期积累了大量提交记录。网页导入对这种仓库非常不友好，后台任务跑几十分钟后容易卡死或报超时。命令行方案相对稳妥，但推送时也可能因为数据量太大、单次 HTTP 请求受限而失败。处理思路有两个。一是把一次大推送拆成多次小推送，先把所有分支推到 GitLab，再单独推标签：git push origin --all git push origin --tags二是调整 Git 的 HTTP 缓冲区大小。走 HTTPS 协议推送大对象时，可以临时加大缓冲区：git config --global http.postBuffer 524288000这个值单位是字节，上面的例子是 500MB。实测很多不明原因的推送中断，把缓冲区调大之后就好了。如果是走 SSH 协议，则不太会遇到这类 HTTP 缓冲区问题。所以我的建议是：gitlab 地址支持 SSH 的话，优先配置 SSH Key，体验会顺滑很多。如果你遇到的是 GitLab 上传文件大小限制，那问题在服务端配置。GitLab 默认有git max file size限制，需要管理员在管理后台或者配置文件中调大，这个改动要重启服务才能生效，最好提前和运维沟通好。5.3 子模块和 LFS 文件如何处理GitHub 仓库里如果用了 submodule（子模块），直接git clone --bare只会拉取子模块的引用记录，不会拉取子模块本身的内容。镜像推送到 GitLab 后，别人 clone 这个项目时会看到子模块目录是空的。处理办法是在裸克隆前先初始化子模块：git clone --recurse-submodules https://github.com/某团队/某项目.git这个命令会连同子模块一起克隆下来。之后推送时，普通git push --all并不会把子模块的内容推送到 GitLab，因为子模块本身就是独立的 Git 仓库，它们的 remote 地址还指向原始 GitHub 地址。所以你还需要单独把每个子模块也镜像到 GitLab，并修改父项目里的.gitmodules文件指向新的子模块地址，再提交这个修改。LFS（Large File Storage）则是另一个常见坑。GitHub 仓库启用了 LFS 后，远程仓库里存的是文件的指针，实际大文件存放在 GitHub LFS 存储服务上。裸克隆时，如果没装git-lfs插件，克隆下来的只是指针文件。装插件后有两条路：让本地裸仓库初始化 LFS 并拉取大文件内容，或者干脆在推送后让 GitLab 端也启用 LFS，再重新 clone 触发大文件下载。实际迁移时我通常先检查仓库里是否用了 LFS：git lfs ls-files如果输出为空说明没用 LFS，省心。如果列出了文件，那迁移后千万记得测试一下大文件能否正常检出，否则团队实际用起来才发现文件损坏，那就被动了。5.4 权限、合规与团队协作的收尾建议仓库迁移到 GitLab 只是完成了“搬东西”这一步，真正让团队顺利用起来还需要收尾。我在多个迁移项目里总结了一套固定动作：确认默认分支设置。GitLab 新建项目默认分支是 main，如果 GitHub 原仓库用 master，迁移后要在 GitLab 项目设置里调整默认分支，否则 MR 的 Target 分支容易选错。配置分支保护。至少把 main/master 分支设为“仅允许 Maintainer 推送”，维持和 GitHub 上一致的保护策略。清理 GitHub 侧的敏感历史。如果仓库包含密钥、数据库密码等敏感内容，直接迁移是危险行为，应该先处理历史提交中的敏感信息再导入。这个要重点提示，迁移动作本身不能成为数据泄露的通道。保留 GitHub 旧仓库一段时间。迁移完成后先别删 GitHub 上的原仓库，保留一到两个月作为回退方案。团队在 GitLab 上稳定运行后再决定去留。写一份简短的迁移说明文档。告诉团队新仓库地址、同步策略、分支规范、CI 状态，让所有人知道工作流切换到了哪里。6. 聊聊我实际跑迁移后的一些心得体会用 GitLab 网页导入给团队做过一次二十多个仓库的批量迁移，全程零代码，网页点按钮加审核权限就完成了大半。也碰到过一个大型仓库，网页导入反复失败，最后在办公室一台能通外网的机器上用裸克隆加推送十五分钟搞定。两种方案不是谁替代谁的关系，而是互补的。从经验角度看，有几个容易被忽略的细节值得多说一句。第一，Token 权限宁多勿少但用后即焚，迁移完把 GitHub PAT 删掉能从源头上防止泄露。第二，GitLab 导入完成后，先让一两个同事实际 clone 和 push 一轮再通知全员切流，比盲目广播“迁移完成”稳妥得多。第三，镜像同步脚本要加日志和失败告警，否则定时任务静默失败，过几天才发现本地 GitLab 落后上游好几个版本，丢失了关键更新。如果你要迁移的仓库数量在几十个以上，可以考虑用 GitLab 的批量导入脚本或者 API 做进一步自动化，但那已经是“有代码”的路线了。对于日常零星同步，网页导入配合命令行增量更新，已经能覆盖绝大多数场景。希望这篇内容能帮你少走一段弯路。