文档

自建Gitlab迁移

更新时间:

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

一、前提条件

请确认工具已安装并运行正常,参见安装本地迁移工具

二、迁移准备

现在,你有一个自建的 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 my$ ./codeup-cli init
【提示】 配置文件路径:/Users/my/config.yaml
【成功】 初始化 config.yaml 成功,路径地址为:/Users/my/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,参见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: projects.csv
    usermappath: users.csv
    workdir: /Users/my/workspace

其中:

usermappath 指定步骤四里用户映射文件路径;

projectlistpath 指定步骤五里迁移库范围文件路径;

workdir 指定迁移的工作目录路径,迁移完成后将自动清理目录;

四、定义 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代码库可见性
groupname/demo,groupname/demo,10
说明

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

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

六、执行迁移

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

image

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

./codeup-cli import --run true 
 # 迁移过程中会展示迁移的细节,如果有问题会显示报错信息
说明
  1. 如 Git 数据迁移失败,该库状态为迁移失败,其他附属成员权限、保护分支、合并请求迁移失败仅做警告,不阻断导入;

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

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

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

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

  • 本页导读 (0)
文档反馈