首页 云效2020 代码管理 代码迁移与同步 自建Gitlab迁移工具(BETA)

自建Gitlab迁移工具(BETA)

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

Codeup-CLI 工具使用方法

简单三步,完成代码批量迁移:

  • 步骤一.根据自身系统下载对应迁移工具;

  • 步骤二.通过命令生成迁移源和目标的配置文件,并完成参数配置;

  • 步骤三.通过命令生成期望导入的代码库列表,以及用户映射配置文件;

  • 步骤四.执行迁移命令,工具将依据步骤二、三生成的配置文件将自建 Gitlab 代码、人员权限、Webhooks、保护分支、开启的合并请求数据迁移至 Codeup 指定企业;

一、工具准备

下载工具

请根据自身系统选择下载迁移工具:

系统类型

下载地址

macOS ARM 64位

工具下载地址

macOS 64位

工具下载地址

Linux 64位

工具下载地址

Linux 32位

工具下载地址

Windows 64位

工具下载链接

Windows 32位

工具下载链接

安装工具

Codeup-CLI 工具下载后可直接使用,请将已下载解压的工具按以下指引放置到命令行执行的目录下即可:

# 建议本地新建一个工作空间,名称可自定义,如”workspace“,迁移完成后可自行删除:
mkdir workspace
cd workspace

# 把 codeup-cli 工具放至该空间下
cp ~/Downloads/codeup-cli ./

# 新建一个目录用于存放三方需要迁移的代码库,名称可自定义,如”repo“
mkdir repo

测试工具

在命令行执行以下命令,确认工具运行正常:

./codeup-cli --help
image

说明

异常提示处理:

  1. 若出现运行工具权限不足相关报错提示,Linux/Mac 请执行以下命令授权:

chmod +x ./codeup-cli
  1. 若出现以下提示,表明下载的工具包和你的系统类型不匹配,请确认系统类型后重新下载对应工具包:

Bad CPU type in executable

二、迁移准备

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

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

  • 代码库 Git 数据

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

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

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

Gitlab 库角色

Codeup 库角色

Owner/Mantainer

库管理员

Developer

库开发者

Repertor/Guest

库浏览者

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

  • 代码库已配置的 Webhooks;

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

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

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

三、定义迁移配置文件

现在我们开始迁移,请输入以下命令,初始化本次迁移所需的配置文件:

./codeup-cli init

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

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

接着根据提示的路径,打开这个 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

username/password

如用HTTP克隆必填

自建 GitLab 平台可用于HTTP克隆的用户名/密码

accessKey

暂无

系统预留字段

secretKey

暂无

系统预留字段

orgID

暂无

系统预留字段

localSSHKeyPath

如用SSH克隆必填

自建 GitLab 平台已配置的 SSH key 对应的本地 key 路径,注意填写完整路径,如 /Users/misha/.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/password

如用HTTP克隆必填

Codeup 可用于HTTP克隆的用户名/密码

accessKey

必填

阿里云的主账号(同时需要作为Codeup目标企业的拥有者)AK

secretKey

必填

阿里云的主账号(同时需要作为Codeup目标企业的拥有者)SK

orgID

必填

期望迁移到的 Codeup 企业ID,可在云效企业管理后台查看

localSSHKeyPath

如用SSH克隆必填

Codeup 已配置的 SSH key 对应的本地 key 路径,注意需填写完整路径,如 /Users/misha/.ssh/id_rsa

以 SSH 方式为例,最简的配置文件内容为:

import:
    source:
        platform: gitlab
        apiEndpoint: https://gitlab.example.com
        accessToken: xxxxx
        host: https://gitlab.my-example.com
        localSSHKeyPath: /Users/misha/.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/misha/.ssh/id_rsa
    projectlistpath: projects.csv
    usermappath: users.csv
    workdir: /Users/misha/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

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

重要

请注意,为了保证迁移时 Codeup 能够识别到对应阿里云用户,请确保该用户已经登录访问过 Codeup。

说明

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

image

五、定义迁移代码库范围

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

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

codeup-cli import --gen project

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

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

其中代码库可见性 0 表示公开性为「私有」,10 表示公开性为「企业内公开」。若自定义时输入任意非 0 的数字将被自动转换为 10,即企业内公开。

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

六、执行迁移

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

image

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

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

说明
  1. 如 Git 数据迁移失败,该库状态为迁移失败,其他附属成员权限、保护分支、合并请求迁移失败仅做警告,不阻断导入;

  2. 若重复执行导入,历史已导入成功的代码库将提示已存在跳过执行,未导入成功的代码库可继续尝试导入;

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

恭喜你,至此已经完成了自建 Gitlab 指定数据的迁移工作,在云效 Codeup 上立即开始托管体验吧!

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

image
阿里云首页 云效2020 相关技术圈