自建Gitlab迁移工具使用指南

自建Gitlab迁移工具指南，迁移工具对自建 Gitlab 服务的数据搬站提供了支持，可以方便地将 Gitlab 的 Git 代码数据、用户权限关系和已开启的合并请求数据进行批量迁移，大幅降低企业迁移成本。

说明

迁移工具包于 2022 年 04 月 13 日进行更新，新增自建 Gitlab 人员权限关系和已开启的合并请求迁移能力，建议该日期前下载工具的用户更新最新版本使用。

注意

建议导入库地址使用 HTTP 协议，后续将基于 HTTP 协议支持仓库同步能力。

工具使用方法

简单三步，完成代码库批量迁移：

步骤一.下载迁移工具；
步骤二.通过命令自动生成阿里云RAM子账号，作为迁移用户映射关系的配置文件；
步骤三.通过命令自动生成期望导入的代码库列表，作为迁移库范围的配置文件；
步骤四.执行迁移命令，工具将依据步骤二、三生成的配置文件将自建 Gitlab 数据迁移至 Codeup 指定企业；

一、工具准备

下载迁移工具，其原理是根据你在自建的 Gitlab 服务里的权限，自动生成相关配置文件，并可以按需调整配置文件内容后，再依据配置文件规则将 Gitlab 数据迁移至 Codeup 企业中。

下载工具

macOS ARM 64位下载地址

macOS 64位下载地址

Linux 64位下载地址

Windows 64位下载地址

安装工具

Windows环境可以跳过安装，直接使用，但需要保证在命令行执行的目录下有已下载的迁移工具。

Linux和macOS，需要将下载得到的文件放在 /usr/local/bin/ 目录下:

1	`mv codeup /usr/local/bin/`

测试工具

在命令行中执行，执行成功会显示工具的帮助信息：

1	`codeup -h`

在 macOS 可能会提示 macOS 无法打开工具，因为无法验证开发者，请通过“系统偏好设置”-“安全性与隐私”-“通用”页面，选择“仍然允许”，来授权 macOS 使用工具

二、迁移计划和准备工作

现在，你有一个自建的 Gitlab 服务，上面有若干个用户，以及若干代码库和已经设置好的代码库成员权限、保护分支规则，正在进行中的合并请求等数据。

本工具可以帮助你进行如下数据的迁移：

代码库 Git 数据
代码库的基本设置：仅包括库的描述信息、库的默认分支设置
代码库的保护分支规则：仅包括分支名、允许推送角色、允许合并角色
代码库的成员信息：根据提供的用户映射配置文件，将 Gitlab 用户映射到 Codeup 的库用户，并将用户添加到 Codeup 的对应代码库成员中，转变为 Codeup 的库角色时有如下映射原则：

Gitlab 库角色	Codeup 库角色
Owner/Mantainer	库管理员
Developer	库开发者
Repertor/Guest	库浏览者

代码库中正在进行中的合并请求（已开启的合并请求）：会在 Codeup 中以迁移操作人的身份创建同名的合并请求，并将能识别到映射关系的评审者进行迁移。不会保留已有的评论、动态和创建人等信息。

其中，代码库成员数据和合并请求数据的迁移是可选的，你可以选择迁移或者不迁移。

假设你已经下载安装好工具，并测试工具正常可运行，已明确迁移的内容：要迁移上述支持的所有数据。我们推荐你遵照下面的迁移计划：

在正式迁移生产库前，建议使用非正式库进行试迁移，保障配置正确后正式迁移；
在迁移操作时建议控制自建 Gitlab 的库变更和写入行为，一旦仓库迁移成功后，重复迁移不会刷新变更的代码数据，即迁移后 Gitlab 的新增内容不会更新至 Codeup；

说明准备工作：

一个阿里云的主账号（同时需要作为云效目标企业的拥有者），以及获取主账号的AK 、SK , 假设是 '$aliyunAk'， '$aliyunSk'

目标期望迁移到的 Codeup 企业ID，假设是 '$orgId'（可在云效企业管理后台查看）

阿里云主账号在 Codeup 的个人访问令牌，要勾选授予权限 write:repo ，假设令牌是’$codeupToken‘

你的 Gitlab 服务地址，假设是 http://mygitlab.com

你的Gitlab管理员账号的 AccessToken（需要授予 read_user, read_api , read_repository 权限），假设为 '$gitlabToken'

以上假设值在下面的工具执行中会用到，请在实际迁移过程中使用你真实的配置信息替换。

三、迁移过程

3.1 迁移 Gitlab 用户权限【可选】

Gitlab 和 Codeup 用户关系存在以下两种情况：

Gitlab 用户已经在 Codeup 上手动自己创建了一个用户（可能同名或不同名）
Gitlab 用户在 Codeup 上没有对应的用户

首先要明确的是 Gitlab 的用户数据和 Codeup 上的用户数据是独立不相关的，对于 Codeup 来说需要你提供映射关系表。

即使你知道 Codeup 上有个叫张三的用户，在 Gitlab 有一个 zhangsan 的用户，两个用户其实是同一个人，那么也是需要告诉工具，两个账号的关联关系。这样就需要一个用户的映射配置文件，迁移工具会根据这个用户映射文件，将 Gitlab 用户权限关系数据迁移到 Codeup 对应代码库内。

接下来的操作，将会帮助你批量完成 Gitlab 用户在 Codeup 上同名用户的创建和关联。

# 假设已经CD到工具所在的目录下，执行下面的命令
 
codeup repo generateUserMap --host=http://mygitlab.com --access_token=$gitlabToken --access_key=$aliyunAk --secret_key=$aliyunSk
 
...
#命令执行成功后，在你指定AK\SK的阿里云主账号下，会批量创建出与Gitlab用户同名的阿里云Ram子账号，并会在当前目录生成一个user-map.csv的文件

打开user-map.csv，其内容的格式是每一行都是 [Gitlab的用户名],[Codeup用户的阿里云ID]，形如：

1 2	`zhangsan,11232342143245234` `lisi,1231312312311`

你可以手动编辑这个文件，增加或删除用户映射的配置（例如部分用户不希望使用自动生成的账号，可以手动将映射关系改为指定的阿里云账号）。

说明

阿里云账号 ID 获取方式：在 https://www.aliyun.com 主页右上角点击头像-账号ID

此时，你可以发现阿里云主账号下对应 Gitlab 中的用户名依次创建出了RAM子账号，现在，需要在云效目标企业中，同步这些子账号成员。

使用当前阿里云主账号，进入云效企业成员管理，点击右上角添加成员，选择邀请企业成员：

全选或勾选期望同步的RAM账号，添加至云效企业中：

至此，你已经完成了Gitlab用户到Codeup用户的创建和映射关系，得到了一个user-map.csv的文件，并将新创建的RAM用户导入至云效的目标企业中了。

3.2 定义迁移的代码库范围

你需要告知迁移工具要迁移的代码库列表范围，这也需要一个配置文件。

可以通过下面操作，自动分析出在Gitlab中的所有代码库并生成这个迁移库范围的配置文件。

codeup repo generate --platform=gitlab --access_token=$gitlabToken --host=http://mygitlab.com
 
...
# 命令执行完成后会在当前目录下生成一个 repo_list_config.csv 的配置文件

打开repo_list_config.csv，其内容格式是每一行都是[库克隆地址],[Codeup代码库路径],[Codeup代码库可见性]，形如

1 2	`#库克隆地址,Codeup代码库路径,Codeup代码库可见性` `http://mygitlab.com/xxxxx/stable.git,xxxxx/stable,10`

你可以手动编辑这个文件，增加或删除期望迁移的代码库范围。

至此，你已经明确了迁移的代码库范围，得到了一个 repo_list_config.csv 的文件。

3.3 基于以上配置文件批量迁移 Gitlab 数据到 Codeup

# 通过ls查看当前的目录的文件（windons的话是dir命令）,确认下有以上两个配置文件
ls
 
repo_list_config.csv
user-map.csv
 
# 执行下面命令开始迁移
codeup repo importGitlab --repo_list_path=repo_list_config.csv --organization=$orgId --access_key=$aliyunAk --secret_key=$aliyunSk --personal_access_token=$codeupToken --import_member=true --user_map_path=user-map.csv --import_merge_request=true --push_protocol=http
 
 
...
 
# 迁移过程中会展示迁移的细节，如果有问题会显示报错信息