自建Gitlab迁移到Region站

使用 Codeup-CLI 工具将自建 GitLab 的 Git 数据、成员权限、Webhook 等批量迁移至云效 Codeup Region 站。

迁移准备

操作前，确认Codeup-CLI工具已安装并运行正常。工具支持迁移以下数据：

代码库 Git 数据：源代码、分支、提交、标签。
代码库的基本设置：仅包括库的描述信息、库的默认分支设置。
代码库的保护分支规则：仅包括分支名、允许推送角色、允许合并角色。
代码库进行中的合并请求：仅包括进行中的合并请求，已关闭的历史记录不迁移。
代码库的成员权限：根据配置的用户映射规则，将 GitLab 用户映射到 Codeup 的库用户，并将用户添加到 Codeup 的对应代码库成员中。
代码库已配置的 Webhooks：将 GitLab 项目 Webhook 同步到 Codeup 对应仓库。

安装并验证工具正常运行后，参照以下迁移计划操作：

正式迁移生产库前，使用非正式库进行试迁移，确认配置正确后再正式迁移。
迁移期间，暂停对自建 GitLab 的写入操作。仓库迁移成功后，重复执行迁移不会同步新增内容。

步骤一：定义迁移配置文件

执行以下命令初始化配置文件：

./codeup-cli init

初始化成功后输出如下：

demo:workspace my$ ./codeup-cli init
【成功】 初始化 config.yaml 成功，路径地址为 /Users/my/config.yaml，请按照帮助文档正确填写配置。

根据提示路径打开 config.yaml，填写以下参数（HTTP 克隆和 SSH 克隆二选一，删除不需要的字段）：

source - 源平台参数配置

参数	是否必填	参数说明
platform	必填	填写 `"gitlab"`。
apiEndpoint	必填	自建 GitLab 平台的首页API 地址，如 `https://gitlab.example.com`。若 API 报 404，可尝试带 `/api/v4` 的地址。
accessToken	必填	GitLab 的 Personal Access Token，需勾选 `read_user`、`read_repository`、`read_api`；如需获取用户邮箱信息用于邮箱映射，还需启用 `admin_mode`。
username	如用 HTTP 克隆必填	自建 GitLab 平台可用于 HTTP 克隆的用户名。
password	如用 HTTP 克隆必填	自建 GitLab 平台可用于 HTTP 克隆的密码或 Token。
localSSHKeyPath	如用 SSH 克隆必填	已配置在 GitLab 的 SSH 公钥对应的本地私钥完整路径，如 `/Users/my/.ssh/id_rsa`。

target - 目标平台参数配置（Region 站）

参数	是否必填	参数说明
host	必填	云效 Codeup Region 站地址，格式为 `https://{orgIdentifier}-{regionId}.devops.aliyuncs.com` 或 `https://{orgIdentifier}-{regionId}.devops.alibabacloudcs.com`。其中 `{orgIdentifier}` 为组织标识，`{regionId}` 为区域 ID（如 `cn-shanghai`、`ap-southeast-1` 等）。
accessKey	必填	具有组织管理->组织成员读写、代码管理->代码仓库读写、代码组读写、提交读写、分支读写、成员读写、Webhook 读写、保护分支读写、合并请求读写权限的个人访问令牌。
username	HTTP 推送必填	Codeup 可用于 HTTP 克隆/推送的用户名。
password	HTTP 推送必填	Codeup 可用于 HTTP 克隆/推送的密码。
localSSHKeyPath	SSH 推送必填	已在 Codeup 配置的 SSH 公钥对应的本地私钥完整路径。

import 公共项

参数	是否必填	参数说明
projectListPath	必填	步骤二：定义迁移代码库范围中生成的`projects.csv`文件路径。
workDir	必填	迁移过程的工作目录路径，迁移完成后会自动清理；需确保有写权限。
memberMapping	可选	成员映射配置（详见下表），仅 GitLab 平台生效。

memberMapping 配置项

参数	默认值	说明
enable	`true`	是否迁移成员。设为 `false` 可完全关闭成员迁移。
registerIfNotFound	`true`	未匹配用户是否自动注册。设为 `false` 时，未匹配到的用户将被跳过。
mappingPriority	`["email", "username"]`	映射优先级列表。按列表顺序依次尝试映射，命中即停止。

以 SSH 方式为例，简化的配置文件内容如下：

version: "v2"

import:
  source:
    platform: "gitlab"
    apiEndpoint: "https://gitlab.example.com"
    accessToken: "glpat-xxxxxxxx"
    localSSHKeyPath: "/Users/my/.ssh/id_rsa"
  target:
    # Region 站地址格式：https://{orgIdentifier}-{regionId}.devops.aliyuncs.com
    host: "https://myorg-cn-shanghai.devops.aliyuncs.com"
    accessKey: "pt-xxxxxxxx"
    localSSHKeyPath: "/Users/my/.ssh/id_rsa"
  # projectlistpath 指定步骤四里迁移库范围文件路径
  projectListPath: "/Users/my/workspace/projects.csv"
  # workdir 指定迁移的工作目录路径，迁移完成后将自动清理目录
  workDir: "/Users/my/workspace"
  # 成员映射配置（可选，以下为默认值）
  memberMapping:
    enable: true
    registerIfNotFound: true
    mappingPriority: ["email", "username"]

步骤二：定义迁移代码库范围

通过以下命令自动分析 GitLab 中的所有代码库，并生成迁移库范围配置文件。

./codeup-cli import --gen project --config=./config.yaml

执行后在 projectListPath 路径生成 projects.csv，格式如下（每行一条记录）：

# GitLab 代码库路径（不含域名）,Codeup 代码库路径,Codeup 代码库可见性
groupname/demo,groupname/demo,10
group/subgroup/repo,group/subgroup/repo,0

代码库可见性说明：

0 表示公开性为「私有」
10 表示公开性为「组织内公开」。若自定义时输入任意非 0 的数字将被自动转换为 10，即组织内公开。

可以手动编辑该文件，增加或删除待迁移的代码库范围。

步骤三：成员映射配置

迁移代码库成员时，工具会自动完成用户映射，无需手动准备映射文件。映射参数说明见memberMapping 配置项。

匹配字段说明

字段	说明
`email`	按 GitLab 用户邮箱匹配目标组织成员。
`username`	按 GitLab 用户名匹配。Codeup 用户名格式通常为 `{gitlabUsername}_{orgIdentifier}`，工具会自动推断 `orgIdentifier` 后缀并去除后匹配。

未匹配用户的处理

未匹配用户处理（ registerIfNotFound: true，默认）：

工具会调用 RegisterMember 接口在目标组织自动创建新用户
新用户的用户名格式为 {gitlabUsername}_{orgIdentifier}
新用户的密码固定为 Yun#xia0，账号首次登录时需要重置密码
创建后将该用户加入代码库，并根据用户在gitlab中的权限转变为 Codeup 的库角色，映射原则如下：
GitLab 库角色
Codeup 库角色
Owner/Maintainer
库管理员
Developer
库开发者
Reporter/Guest
库浏览者
当 registerIfNotFound: false 时，未匹配用户将被跳过，仅输出警告日志。

示例配置

import:
  # ... 其他配置
  
  # 关闭成员迁移
  memberMapping:
    enable: false
  
  # 或：开启成员迁移但不自动创建新用户
  memberMapping:
    enable: true
    registerIfNotFound: false
  
  # 或：仅按 username 映射
  memberMapping:
    mappingPriority: ["username"]
  
  # 或：先 username 后 email
  memberMapping:
    mappingPriority: ["username", "email"]

步骤四：执行迁移

确认工作目录下配置文件和存放代码库的文件夹（如自定义的 workDir）已准备完毕，执行以下命令启动迁移：

./codeup-cli import --run true --config=./config.yaml
# 迁移过程中会展示迁移的细节，如果有问题会显示报错信息

说明：

如 Git 数据迁移失败，该库状态为迁移失败，其他附属成员权限、保护分支、Webhook 迁移失败仅做警告，不阻断导入。
若重复执行导入，历史已导入成功的代码库将提示已存在跳过执行，未导入成功的代码库可继续尝试导入。

迁移完成后，前往 Codeup 组织查看已迁移的代码库和成员信息，确认迁移结果。

Region 站支持的 Region 列表

说明

实际支持的 Region 以云效控制台展示为准，以下列表仅供参考。

Region ID	区域
cn-shanghai	华东2（上海）
cn-hangzhou	华东1（杭州）
cn-beijing	华北2（北京）
cn-shenzhen	华南1（深圳）
ap-southeast-1	亚太东南1（新加坡）

常见问题

GitLab API 报 404 错误

将 import.source.apiEndpoint 改为带 /api/v4 的地址，如 https://gitlab.example.com/api/v4。

克隆失败

检查 import.source.localSSHKeyPath 配置，在本机执行 ssh -T git@<GitLab 主机> 测试 SSH 连接是否正常。

推送失败

检查目标 localSSHKeyPath 或 username/password 配置，以及目标平台是否已添加公钥/账号。

Token 无效

确认迁移 Token 已填入 import.target.accessKey，且具备代码库、代码组、组织成员、Webhook、保护分支、分支、成员等读写权限。

Region 站地址格式错误

确保 host 格式正确：https://{orgIdentifier}-{regionId}.devops.aliyuncs.com，其中 orgIdentifier 为组织标识（可在云效组织管理后台查看），regionId 为区域 ID。

GitLab 库角色	Codeup 库角色
Owner/Maintainer	库管理员
Developer	库开发者
Reporter/Guest	库浏览者