一、前提條件

操作前，請確認(rèn)工具已安裝并運(yùn)行正常，具體請參見安裝本地遷移工具。

二、遷移準(zhǔn)備

例如，您有一個(gè)自建的Gitlab服務(wù)，上面有若干個(gè)用戶，以及若干代碼庫和已經(jīng)設(shè)置好的代碼庫成員權(quán)限、保護(hù)分支規(guī)則，正在進(jìn)行合并請求中等。

本工具可以幫助您進(jìn)行如下數(shù)據(jù)的遷移：

• 代碼庫Git數(shù)據(jù)。

• 代碼庫的基本設(shè)置：僅包括庫的描述信息、庫的默認(rèn)分支設(shè)置。

• 代碼庫的保護(hù)分支規(guī)則：僅包括分支名、允許推送角色、允許合并角色。

• 代碼庫的成員權(quán)限：根據(jù)提供的用戶映射配置文件，將Gitlab用戶映射到Codeup的庫用戶，并將用戶添加到Codeup的對應(yīng)代碼庫成員中，轉(zhuǎn)變?yōu)镃odeup的庫角色時(shí)有如下映射原則。

  Gitlab 庫角色	Codeup 庫角色
  Owner/Mantainer	庫管理員
  Developer	庫開發(fā)者
  Repertor/Guest	庫瀏覽者

• 代碼庫中正在進(jìn)行中的合并請求（已開啟的合并請求）：會在Codeup中以遷移操作人的身份創(chuàng)建同名的合并請求，并將能識別到映射關(guān)系的評審者進(jìn)行遷移。不會保留已有的評論、動態(tài)和創(chuàng)建人等信息。

• 代碼庫已配置的Webhooks。

如果您已經(jīng)安裝好工具，并測試工具正常可運(yùn)行，確認(rèn)遷移的數(shù)據(jù)內(nèi)容如上述。我們推薦您遵照下面的遷移計(jì)劃：

1. 在正式遷移生產(chǎn)庫前，建議使用非正式庫進(jìn)行試遷移，保障配置正確后在進(jìn)行正式遷移。

2. 在遷移操作時(shí)建議控制自建Gitlab的庫變更和寫入行為，一旦倉庫遷移成功后，重復(fù)遷移不會刷新變更的代碼數(shù)據(jù)，即遷移后Gitlab的新增內(nèi)容不會更新至Codeup。

三、定義遷移配置文件

1. 開始遷移前，請輸入以下命令，初始化本次遷移所需的配置文件。

   ./codeup-cli init

   此時(shí)可以看到配置文件初始化成功的提示。

   demo:workspace my$ ./codeup-cli init
   【提示】 配置文件路徑：/Users/my/config.yaml
   【成功】 初始化 config.yaml 成功，路徑地址為：/Users/my/config.yaml，請按照幫助文檔正確填寫配置。

2. 接著根據(jù)提示的路徑，打開這個(gè)config.yaml文件，開始填寫源和目標(biāo)平臺的配置參數(shù)，用于代碼庫拉取和導(dǎo)入。

   配置文件字段說明如下，請?zhí)顚懕靥畹淖侄危?b>其中HTTP或SSH克隆二選一填寫，不需要的字段請自行刪除：

   source - 源平臺參數(shù)配置	是否必填	參數(shù)說明
   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，需勾選授予權(quán)限r(nóng)ead_api，參見Access Token 訪問令牌如何獲取？。
   username	如用HTTP克隆必填	自建GitLab平臺可用于HTTP克隆的用戶名。
   password	如用HTTP克隆必填	自建GitLab平臺可用于HTTP克隆的密碼。
   accessKey	暫無	系統(tǒng)預(yù)留字段。
   secretKey	暫無	系統(tǒng)預(yù)留字段。
   orgID	暫無	系統(tǒng)預(yù)留字段。
   localSSHKeyPath	如用SSH克隆必填	自建GitLab平臺已配置的SSH key對應(yīng)的本地私鑰key路徑，注意填寫完整路徑，如 /Users/my/.ssh/id_rsa。 具體路徑請根據(jù)實(shí)際本機(jī)私鑰存放路徑填寫。
   asMember	必填	true：僅遷移操作人是成員的代碼庫； false：遷移操作人有讀權(quán)限的庫（針對整站搬遷的場景，用戶可能擁有平臺Admin權(quán)限，但并不屬于庫成員，此時(shí)可將該參數(shù)設(shè)置為 false，此時(shí)會查詢所有有讀權(quán)限的庫，而不限于必須有庫成員權(quán)限）。

   target - 目標(biāo)平臺參數(shù)配置	是否必填	參數(shù)說明
   platform	必填	codeup （初始化已配置，請勿修改）。
   apiEndpoint	必填	devops.cn-hangzhou.aliyuncs.com（初始化已配置，請勿修改）。
   host	必填	codeup.aliyun.com（初始化已配置，請勿修改）。
   accessToken	必填	阿里云主賬號在Codeup的個(gè)人訪問令牌，需勾選授予權(quán)限 write:repo，參見個(gè)人訪問令牌。
   username	如用HTTP克隆必填	Codeup可用于HTTP克隆的用戶名
   password	如用HTTP克隆必填	Codeup可用于HTTP克隆的密碼
   accessKey	必填	阿里云的主賬號（同時(shí)需要作為Codeup目標(biāo)企業(yè)的擁有者）AK （AccessKey ID）參見如何獲取
   secretKey	必填	阿里云的主賬號（同時(shí)需要作為Codeup目標(biāo)企業(yè)的擁有者）SK（AccessKey Secret）參見如何獲取
   orgID	必填	期望遷移到的Codeup企業(yè)ID，可在云效企業(yè)管理后臺查看
   localSSHKeyPath	如用SSH克隆必填	Codeup已配置的SSH key對應(yīng)的本地私鑰key路徑，注意需填寫完整路徑，如 /Users/my/.ssh/id_rsa。 具體路徑請根據(jù)實(shí)際本機(jī)私鑰存放路徑填寫。

   以SSH方式為例，簡化的配置文件內(nèi)容如下：

   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用戶關(guān)系存在以下兩種情況：

1. GitLab用戶已經(jīng)在Codeup上手動自己創(chuàng)建了一個(gè)用戶（可能同名或不同名）。

2. Gitlab用戶在Codeup上沒有對應(yīng)的用戶。

首先要明確的是GitLab的用戶數(shù)據(jù)和Codeup上的用戶數(shù)據(jù)是獨(dú)立不相關(guān)的，對于Codeup來說需要提供映射關(guān)系表。

即使您知道Codeup上有個(gè)叫張三的用戶，在Gitlab有一個(gè)zhangsan的用戶，兩個(gè)用戶其實(shí)是同一個(gè)人，那么也是需要告訴工具，兩個(gè)賬號的關(guān)聯(lián)關(guān)系。這樣就需要一個(gè)用戶的映射配置文件，遷移工具會根據(jù)這個(gè)用戶映射文件，將GitLab用戶權(quán)限關(guān)系數(shù)據(jù)遷移到Codeup對應(yīng)代碼庫內(nèi)。

使用以下命令初始化三方平臺與云效成員映射文件：

./codeup-cli import --gen user

在工作目錄下可以看到生成了一個(gè)用于描述用戶映射關(guān)系的文件users.csv，打開文件，其內(nèi)容的格式是每一行都是 [Gitlab的用戶名],[Codeup用戶的阿里云ID]，示例如下：

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

您可以手動編輯這個(gè)文件，增加或刪除用戶映射的配置。

五、定義遷移代碼庫范圍

您需要告知遷移工具要遷移的代碼庫列表范圍，這也需要一個(gè)配置文件。

可以通過以下命令，自動分析出在GitLab中的所有代碼庫并生成這個(gè)遷移庫范圍的配置文件。

./codeup-cli import --gen project

命令執(zhí)行完成后會在當(dāng)前目錄下生成一個(gè)projects.csv的配置文件，打開文件，其內(nèi)容格式是每一行都是[GitLab代碼庫路徑]，[Codeup代碼庫路徑]，[Codeup代碼庫可見性]，形如：

#GitLab代碼庫路徑（不包括域名前綴）,Codeup代碼庫路徑,Codeup代碼庫可見性
groupname/demo,groupname/demo,10

您可以手動編輯這個(gè)文件，增加或刪除期望遷移的代碼庫范圍。至此，您已經(jīng)明確了遷移的代碼庫范圍。

六、執(zhí)行遷移

即將大功告成，請確認(rèn)目前工作目錄下3個(gè)配置文件（遷移配置文件、用戶映射文件、代碼庫范圍文件）和存放代碼庫的文件夾（例如自定義的“repo”）已準(zhǔn)備完畢：

通過以下命令啟動執(zhí)行遷移：

./codeup-cli import --run true 
 # 遷移過程中會展示遷移的細(xì)節(jié)，如果有問題會顯示報(bào)錯(cuò)信息

工具執(zhí)行完后，如果一切正常，您便可以前往Codeup企業(yè)查看已遷移的代碼庫、成員和合并請求等信息，以確認(rèn)遷移無誤。

遷移過程中遇到無法處理的問題，請?zhí)砑俞斸斎鹤稍兗夹g(shù)支持：32027065。