自建Gitlab迁移

一、前提条件

操作前，请确认工具已安装并运行正常，具体请参见安装迁移工具。

二、迁移准备

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

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

• 代码库Git数据。

• 代码库的基本设置：仅包括库的描述信息、库的默认分支设置。

• 代码库的保护分支规则：仅包括分支名、允许推送角色、允许合并角色。

• 代码库的成员权限：根据提供的用户映射配置文件，将Gitlab用户映射到Codeup的库用户，并将用户添加到Codeup的对应代码库成员中，转变为Codeup的库角色时有如下映射原则。

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

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

• 代码库已配置的Webhooks。

如果您已经安装好工具，并测试工具正常可运行，确认迁移的数据内容如上述。我们推荐您遵照下面的迁移计划：

1. 在正式迁移生产库前，建议使用非正式库进行试迁移，保障配置正确后在进行正式迁移。

2. 在迁移操作时建议控制自建Gitlab的库变更和写入行为，一旦仓库迁移成功后，重复迁移不会刷新变更的代码数据，即迁移后Gitlab的新增内容不会更新至Codeup。

三、定义迁移配置文件

1. 开始迁移前，请输入以下命令，初始化本次迁移所需的配置文件。

   ./codeup-cli init

   此时可以看到配置文件初始化成功的提示。

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

2. 接着根据提示的路径，打开这个config.yaml文件，开始填写源和目标平台的配置参数，用于代码库拉取和导入。

   配置文件字段说明如下，请填写必填的字段，其中HTTP或SSH克隆二选一填写，不需要的字段请自行删除：

   source - 源平台参数配置	是否必填	参数说明
   platform	必填	暂支持：gitlab
   apiEndpoint	必填	自建GitLab平台的首页地址 ，如 https://gitlab.example.com。
   host	必填	GitLab代码库克隆URL的一级地址，如 HTTP 克隆地址为“https://gitlab.my-example.com/demo.git”，则host 为“https://gitlab.my-example.com”。
   accessToken	必填	GitLab管理员账号的AccessToken，需勾选授予权限read_api，参见Access Token访问令牌如何获取？。
   username	如用HTTP克隆必填	自建GitLab平台可用于HTTP克隆的用户名。
   password	如用HTTP克隆必填	自建GitLab平台可用于HTTP克隆的密码。
   accessKey	暂无	系统预留字段。
   secretKey	暂无	系统预留字段。
   orgID	暂无	系统预留字段。
   localSSHKeyPath	如用SSH克隆必填	自建GitLab平台已配置的SSH key对应的本地私钥key路径，注意填写完整路径，如 /Users/my/.ssh/id_rsa。 具体路径请根据实际本机私钥存放路径填写。
   asMember	必填	true：仅迁移操作人是成员的代码库； false：迁移操作人有读权限的库（针对整站搬迁的场景，用户可能拥有平台Admin权限，但并不属于库成员，此时可将该参数设置为 false，此时会查询所有有读权限的库，而不限于必须有库成员权限）。

   target - 目标平台参数配置	是否必填	参数说明
   platform	必填	codeup （初始化已配置，请勿修改）。
   apiEndpoint	必填	devops.cn-hangzhou.aliyuncs.com（初始化已配置，请勿修改）。
   host	必填	codeup.aliyun.com（初始化已配置，请勿修改）。
   accessToken	必填	阿里云主账号在Codeup的个人访问令牌，需勾选授予权限 write:repo，参见个人访问令牌。
   username	如用HTTP克隆必填	Codeup可用于HTTP克隆的用户名
   password	如用HTTP克隆必填	Codeup可用于HTTP克隆的密码
   accessKey	必填	阿里云的主账号（同时需要作为Codeup目标组织的拥有者）AK （AccessKey ID）参见如何获取
   secretKey	必填	阿里云的主账号（同时需要作为Codeup目标组织的拥有者）SK（AccessKey Secret）参见如何获取
   orgID	必填	期望迁移到的Codeup组织ID，可在云效组织管理后台查看
   localSSHKeyPath	如用SSH克隆必填	Codeup已配置的SSH key对应的本地私钥key路径，注意需填写完整路径，如 /Users/my/.ssh/id_rsa。 具体路径请根据实际本机私钥存放路径填写。

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

   import:
       source:
           platform: gitlab
           apiEndpoint: https://gitlab.example.com
           accessToken: xxxxx
           host: https://gitlab.my-example.com
           localSSHKeyPath: /Users/my/.ssh/id_rsa
           asMember：true
       target:
           platform: codeup
           apiEndpoint: devops.cn-hangzhou.aliyuncs.com
           accessToken: xxxxx
           host: codeup.aliyun.com
           accessKey: xxxxx
           secretKey: xxxxx
           orgID: xxxxx
           localSSHKeyPath: /Users/my/.ssh/id_rsa
       # projectlistpath指定步骤五里迁移库范围文件路径。
       projectlistpath: projects.csv
       # usermappath指定步骤四里用户映射文件路径。
       usermappath: users.csv
       # workdir指定迁移的工作目录路径，迁移完成后将自动清理目录。
       workdir: /Users/my/workspace

四、定义 Gitlab 用户映射文件（可选）

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

1. GitLab用户已经在Codeup上手动自己创建了一个用户（可能同名或不同名）。

2. Gitlab用户在Codeup上没有对应的用户。

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

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

使用以下命令初始化三方平台与云效成员映射文件：

./codeup-cli import --gen user

在工作目录下可以看到生成了一个用于描述用户映射关系的文件users.csv，打开文件，其内容的格式是每一行都是 [Gitlab的用户名],[Codeup用户的阿里云ID]，示例如下：

#GitLab用户名（username）,Codeup用户的阿里云ID
zhangsan,11232342143245234
lisi,1231312312311

您可以手动编辑这个文件，增加或删除用户映射的配置。

五、定义迁移代码库范围

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

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

./codeup-cli import --gen project

命令执行完成后会在当前目录下生成一个projects.csv的配置文件，打开文件，其内容格式是每一行都是[GitLab代码库路径]，[Codeup代码库路径]，[Codeup代码库可见性]，形如：

#GitLab代码库路径（不包括域名前缀）,Codeup代码库路径,Codeup代码库可见性
groupname/demo,groupname/demo,10

您可以手动编辑这个文件，增加或删除期望迁移的代码库范围。至此，您已经明确了迁移的代码库范围。

六、执行迁移

即将大功告成，请确认目前工作目录下3个配置文件（迁移配置文件、用户映射文件、代码库范围文件）和存放代码库的文件夹（例如自定义的“repo”）已准备完毕：

通过以下命令启动执行迁移：

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

工具执行完后，如果一切正常，您便可以前往Codeup组织查看已迁移的代码库、成员和合并请求等信息，以确认迁移无误。

迁移过程中遇到无法处理的问题，请添加钉钉群咨询技术支持：32027065。