如何从GitLab.com迁移群组、子群组及项目至自建GitLab实例？

关于迁移可行性的明确结论 #

官方文档提到的「项目资源迁移功能」指的是GitLab内部的批量项目导入导出能力：

• 自建GitLab默认关闭bulk_import_projects功能标志，开启后可接收批量项目迁移请求，但GitLab.com作为源端，不支持发起这类批量项目迁移请求——这意味着官方的批量迁移路径走不通，但并非完全无法迁移项目，可以通过其他官方支持的方式完成。

自动化迁移方法 #

方法1：基于GitLab API的批量导入导出（推荐，保留完整项目数据） #

这是官方支持的方案，能完整保留项目的代码、issues、合并请求、wiki、权限配置等所有数据，适合需要完整迁移的场景：

1. 准备权限令牌：
   • GitLab.com令牌：需拥有read_api、read_repository权限
   • 自建GitLab令牌：需拥有write_api、create_project权限
2. 编写脚本批量处理流程：
   • 调用API获取目标群组及子群组下的所有项目列表
   • 对每个项目发起GitLab.com侧的导出请求
   • 轮询导出状态，完成后下载导出包
   • 调用自建GitLab的导入API上传导出包完成迁移
     核心命令示例（结合curl和jq）：

   # 获取GitLab.com群组下的所有项目ID（含子群组）
   curl --header "PRIVATE-TOKEN: <GITLAB_COM_TOKEN>" "https://gitlab.com/api/v4/groups/<GROUP_ID>/projects?include_subgroups=true" | jq '.[] | .id'
   
   # 发起单个项目导出请求
   curl --request POST --header "PRIVATE-TOKEN: <GITLAB_COM_TOKEN>" "https://gitlab.com/api/v4/projects/<PROJECT_ID>/export"
   
   # 轮询导出状态（直到返回"finished"）
   curl --header "PRIVATE-TOKEN: <GITLAB_COM_TOKEN>" "https://gitlab.com/api/v4/projects/<PROJECT_ID>/export" | jq '.export_status'
   
   # 下载导出包
   curl --header "PRIVATE-TOKEN: <GITLAB_COM_TOKEN>" "https://gitlab.com/api/v4/projects/<PROJECT_ID>/export/download" --output project_export.tar.gz
   
   # 上传至自建GitLab完成导入
   curl --request POST --header "PRIVATE-TOKEN: <SELF_HOSTED_TOKEN>" \
     --form "path=<PROJECT_NAME>" --form "namespace=<TARGET_GROUP_PATH>" \
     --form "file=@project_export.tar.gz" "https://<SELF_HOSTED_GITLAB_DOMAIN>/api/v4/projects/import"
   

方法2：Git克隆+推送（仅迁移代码，丢失非代码资源） #

如果仅需迁移代码仓库，不需要issues、合并请求等非代码数据，可采用这种极简批量方式：

1. 导出GitLab.com群组下所有项目的SSH/HTTPS地址列表
2. 编写脚本批量克隆并推送：

   # 循环处理项目列表文件中的仓库地址
   for repo_url in $(cat repo_list.txt); do
     repo_name=$(basename $repo_url .git)
     git clone --mirror $repo_url
     cd $repo_name.git
     git remote add self-hosted <SELF_HOSTED_REPO_URL>
     git push self-hosted --mirror
     cd .. && rm -rf $repo_name.git
   done
   

方法3：社区封装脚本工具 #

可使用社区维护的批量迁移脚本（如Python/Go编写的工具），这类工具已封装API调用逻辑，只需配置令牌、群组ID等参数即可运行，减少自行编写脚本的工作量。

内容的提问来源于stack exchange，提问作者Ricardo Casimiro