GitHub到GitLab一键迁移自动化方案与实践

1. 项目背景与核心价值

在团队协作开发中，我们经常需要将GitHub上的优秀开源项目迁移到内网GitLab服务器进行二次开发或内部研究。传统方式需要手动下载zip包再上传，或者通过git命令中转，整个过程繁琐低效。这个方案通过自动化工具链实现一键迁移，特别适合以下场景：

• 企业内网开发环境需要隔离外部代码库
• 需要对开源项目进行定制化修改并保留完整git历史
• 团队希望集中管理所有项目到自建GitLab实例

我所在的技术团队每周需要处理20+个开源项目的内网迁移，手动操作平均耗时15分钟/项目。采用这套方案后，迁移时间缩短到30秒内，且完全避免人为操作失误。

2. 完整技术方案设计

2.1 系统架构与组件选型

方案采用Bash脚本作为核心控制器，配合Git和GitLab API实现全流程自动化：

code复制[GitHub Repo] → [Git Clone] → [Mirror Push] → [GitLab Repo]
                ↑            ↑
           Bash Script    GitLab API

关键组件说明：

• git：2.23+版本（需支持--mirror参数）
• curl：7.68+版本（用于API调用）
• jq：1.6+版本（JSON数据处理）

提示：选择Bash而非Python/Ruby等方案，是考虑到：

1. 所有Linux/macOS系统原生支持
2. 无需额外依赖环境
3. 与git命令无缝集成

2.2 环境准备清单

在开始前需要确认：

1. 本地已安装git并配置好GitHub访问权限
2. 目标GitLab服务器地址及API访问令牌
3. 足够的磁盘空间（建议预留源仓库3倍大小）

3. 详细实现步骤

3.1 获取GitLab API访问凭证

在GitLab面板创建Personal Access Token：

1. 进入User Settings → Access Tokens
2. 勾选api和write_repository权限
3. 记录生成的token字符串（页面关闭后不可见）

bash复制# 环境变量配置示例
export GITLAB_URL="https://gitlab.example.com"
export GITLAB_TOKEN="glpat-xxxxxxxx"

3.2 核心迁移脚本实现

创建github_to_gitlab.sh脚本：

bash复制#!/bin/bash

# 参数校验
if [ $# -ne 3 ]; then
  echo "Usage: $0 <github_repo> <gitlab_group> <project_name>"
  exit 1
fi

GH_REPO=$1
GL_GROUP=$2
PROJECT_NAME=$3

# 临时目录
TMP_DIR=$(mktemp -d)

# 步骤1：克隆GitHub仓库（含所有分支和标签）
git clone --mirror "https://github.com/${GH_REPO}.git" $TMP_DIR
cd $TMP_DIR || exit

# 步骤2：在GitLab创建空白项目
PROJECT_ID=$(curl -s --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  -X POST "$GITLAB_URL/api/v4/projects" \
  -d "name=$PROJECT_NAME&namespace_id=$GL_GROUP" | jq -r '.id')

# 步骤3：推送所有引用到GitLab
git push --mirror "$GITLAB_URL/$GL_GROUP/$PROJECT_NAME.git"

# 清理
cd ..
rm -rf $TMP_DIR

3.3 脚本使用示例

迁移TensorFlow模型花园项目：

bash复制chmod +x github_to_gitlab.sh
./github_to_gitlab.sh tensorflow/models 123 tensorflow-models

其中123是GitLab中的群组ID，可通过API获取：

bash复制curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" "$GITLAB_URL/api/v4/groups"

4. 高级功能扩展

4.1 自动同步更新

添加定时任务实现GitHub到GitLab的持续同步：

bash复制# 每周日凌晨3点执行同步
0 3 * * 0 /path/to/github_to_gitlab.sh tensorflow/models 123 tensorflow-models

4.2 批量迁移处理

通过CSV文件批量处理多个项目：

bash复制while IFS=, read -r gh_repo gl_group project_name; do
  ./github_to_gitlab.sh "$gh_repo" "$gl_group" "$project_name"
done < projects.csv

CSV格式示例：

code复制tensorflow/models,123,tf-models
pytorch/vision,456,torch-vision

5. 常见问题排查

5.1 权限错误处理

错误现象：

code复制remote: HTTP Basic: Access denied
fatal: Authentication failed

解决方案：

1. 确认GitLab Token具有write_repository权限
2. 检查GitLab URL是否包含https前缀
3. 尝试重新生成Access Token

5.2 大仓库超时问题

对于超过1GB的仓库：

1. 增加git缓冲区大小：

   bash复制git config --global http.postBuffer 524288000
   

2. 分步传输：

   bash复制git push --mirror --no-verify
   

5.3 分支丢失问题

如果发现部分分支未同步：

1. 检查GitHub源仓库是否包含该分支
2. 执行git fetch --all强制更新
3. 重新运行迁移脚本

6. 性能优化技巧

1. 并行处理：使用GNU parallel工具加速批量迁移

   bash复制cat projects.csv | parallel --colsep ',' ./github_to_gitlab.sh {1} {2} {3}
   

2. 本地缓存：对频繁同步的项目保留本地镜像

   bash复制git config --global remote.origin.mirror true
   

3. 增量同步：通过--depth=1参数仅同步最新变更

   bash复制git fetch --depth=1
   

我在实际使用中发现，对于超过500MB的仓库，采用SSH协议（git@gitlab.com:group/project.git）比HTTPS协议传输速度提升约40%。但需要提前配置好SSH密钥认证。