Alibaba Cloud DevOps：自建Gitlab遷移到Region站

使用 Codeup-CLI 工具將自建 GitLab 的 Git 資料、成員許可權、Webhook 等批量遷移至雲效 Codeup Region 站。

遷移準備

操作前，確認Codeup-CLI工具已安裝並運行正常。工具支援遷移以下資料：

程式碼程式庫 Git 資料：原始碼、分支、提交、標籤。
程式碼程式庫的基本設定：僅包括庫的描述資訊、庫的預設分支設定。
程式碼程式庫的保護分支規則：僅包括分支名、允許推送角色、允許合并角色。
程式碼程式庫進行中的合并請求：僅包括進行中的合并請求，已關閉的記錄不遷移。
程式碼程式庫的成員許可權：根據配置的使用者映射規則，將 GitLab 使用者映射到 Codeup 的庫使用者，並將使用者添加到 Codeup 的對應程式碼程式庫成員中。
程式碼程式庫已配置的 Webhooks：將 GitLab 專案 Webhook 同步到 Codeup 對應倉庫。

安裝並驗證工具正常運行後，參照以下遷移計劃操作：

正式遷移生產庫前，使用非正式庫進行試遷移，確認配置正確後再正式遷移。
遷移期間，暫停對自建 GitLab 的寫入操作。倉庫遷移成功後，重複執行遷移不會同步新增內容。

步驟一：定義遷移設定檔

執行以下命令初始化設定檔：

./codeup-cli init

初始化成功後輸出如下：

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

根據提示路徑開啟 config.yaml，填寫以下參數（HTTP 複製和 SSH 複製二選一，刪除不需要的欄位）：

source - 源平台參數配置

參數	是否必填	參數說明
platform	必填	填寫 `"gitlab"`。
apiEndpoint	必填	自建 GitLab 平台的首頁API 地址，如 `https://gitlab.example.com`。若 API 報 404，可嘗試帶 `/api/v4` 的地址。
accessToken	必填	GitLab 的 Personal Access Token，需勾選 `read_user`、`read_repository`、`read_api`；如需擷取使用者郵箱資訊用於郵箱映射，還需啟用 `admin_mode`。
username	如用 HTTP 複製必填	自建 GitLab 平台可用於 HTTP 複製的使用者名稱。
password	如用 HTTP 複製必填	自建 GitLab 平台可用於 HTTP 複製的密碼或 Token。
localSSHKeyPath	如用 SSH 複製必填	已配置在 GitLab 的 SSH 公開金鑰對應的本地私密金鑰完整路徑，如 `/Users/my/.ssh/id_rsa`。

target - 目標平台參數配置（Region 站）

參數	是否必填	參數說明
host	必填	雲效 Codeup Region 站地址，格式為 `https://{orgIdentifier}-{regionId}.devops.aliyuncs.com` 或 `https://{orgIdentifier}-{regionId}.devops.alibabacloudcs.com`。其中 `{orgIdentifier}` 為組織標識，`{regionId}` 為地區 ID（如 `cn-shanghai`、`ap-southeast-1` 等）。
accessKey	必填	具有組織管理->組織成員讀寫、代碼管理->代碼倉庫讀寫、程式碼群組讀寫、提交讀寫、分支讀寫、成員讀寫、Webhook 讀寫、保護分支讀寫、合并請求讀寫許可權的個人存取權杖。
username	HTTP 推送必填	Codeup 可用於 HTTP 複製/推送的使用者名稱。
password	HTTP 推送必填	Codeup 可用於 HTTP 複製/推送的密碼。
localSSHKeyPath	SSH 推送必填	已在 Codeup 配置的 SSH 公開金鑰對應的本地私密金鑰完整路徑。

import 公用項

參數	是否必填	參數說明
projectListPath	必填	步驟二：定義遷移程式碼程式庫範圍中產生的`projects.csv`檔案路徑。
workDir	必填	遷移過程的工作目錄路徑，遷移完成後會自動清理；需確保有寫入權限。
memberMapping	可選	成員映射配置（詳見下表），僅 GitLab 平台生效。

memberMapping 配置項

參數	預設值	說明
enable	`true`	是否遷移成員。設為 `false` 可完全關閉成員遷移。
registerIfNotFound	`true`	未匹配使用者是否自動註冊。設為 `false` 時，未匹配到的使用者將被跳過。
mappingPriority	`["email", "username"]`	映射優先順序列表。按列表順序依次嘗試映射，命中即停止。

以 SSH 方式為例，簡化的設定檔內容如下：

version: "v2"

import:
  source:
    platform: "gitlab"
    apiEndpoint: "https://gitlab.example.com"
    accessToken: "glpat-xxxxxxxx"
    localSSHKeyPath: "/Users/my/.ssh/id_rsa"
  target:
    # Region 站地址格式：https://{orgIdentifier}-{regionId}.devops.aliyuncs.com
    host: "https://myorg-cn-shanghai.devops.aliyuncs.com"
    accessKey: "pt-xxxxxxxx"
    localSSHKeyPath: "/Users/my/.ssh/id_rsa"
  # projectlistpath 指定步驟四裡遷移庫範圍檔案路徑
  projectListPath: "/Users/my/workspace/projects.csv"
  # workdir 指定遷移的工作目錄路徑，遷移完成後將自動清理目錄
  workDir: "/Users/my/workspace"
  # 成員映射配置（可選，以下為預設值）
  memberMapping:
    enable: true
    registerIfNotFound: true
    mappingPriority: ["email", "username"]

步驟二：定義遷移程式碼程式庫範圍

通過以下命令自動分析 GitLab 中的所有程式碼程式庫，並產生遷移庫範圍設定檔。

./codeup-cli import --gen project --config=./config.yaml

執行後在 projectListPath 路徑產生 projects.csv，格式如下（每行一條記錄）：

# GitLab 程式碼程式庫路徑（不含網域名稱）,Codeup 程式碼程式庫路徑,Codeup 程式碼程式庫可見度
groupname/demo,groupname/demo,10
group/subgroup/repo,group/subgroup/repo,0

程式碼程式庫可見度說明：

0 表示公開性為「私人」
10 表示公開性為「組織內公開」。若自訂時輸入任意非 0 的數字將被自動轉換為 10，即組織內公開。

可以手動編輯該檔案，增加或刪除待遷移的程式碼程式庫範圍。

步驟三：成員映射配置

遷移程式碼程式庫成員時，工具會自動完成使用者映射，無需手動準備對應檔。映射參數說明見memberMapping 配置項。

匹配欄位說明

欄位	說明
`email`	按 GitLab 使用者郵箱匹配目標組織成員。
`username`	按 GitLab 使用者名稱匹配。Codeup 使用者名稱格式通常為 `{gitlabUsername}_{orgIdentifier}`，工具會自動推斷 `orgIdentifier` 尾碼並去除後匹配。

未匹配使用者的處理

未匹配使用者處理（ registerIfNotFound: true，預設）：

工具會調用 RegisterMember 介面在目標組織自動建立新使用者
新使用者的使用者名稱格式為 {gitlabUsername}_{orgIdentifier}
新使用者的密碼固定為 Yun#xia0，帳號首次登入時需要重設密碼
建立後將該使用者加入程式碼程式庫，並根據使用者在gitlab中的許可權轉變為 Codeup 的庫角色，映射原則如下：
GitLab 庫角色
Codeup 庫角色
Owner/Maintainer
庫管理員
Developer
庫開發人員
Reporter/Guest
庫瀏覽者
當 registerIfNotFound: false 時，未匹配使用者將被跳過，僅輸出警告日誌。

樣本配置

import:
  # ... 其他配置
  
  # 關閉成員遷移
  memberMapping:
    enable: false
  
  # 或：開啟成員遷移但不自動建立新使用者
  memberMapping:
    enable: true
    registerIfNotFound: false
  
  # 或：僅按 username 映射
  memberMapping:
    mappingPriority: ["username"]
  
  # 或：先 username 後 email
  memberMapping:
    mappingPriority: ["username", "email"]

步驟四：執行遷移

確認工作目錄下設定檔和存放程式碼程式庫的檔案夾（如自訂的 workDir）已準備完畢，執行以下命令啟動遷移：

./codeup-cli import --run true --config=./config.yaml
# 遷移過程中會展示遷移的細節，如果有問題會顯示報錯資訊

說明：

如 Git 資料移轉失敗，該庫狀態為遷移失敗，其他附屬成員許可權、保護分支、Webhook 遷移失敗僅做警告，不阻斷匯入。
若重複執行匯入，歷史已匯入成功的程式碼程式庫將提示已存在跳過執行，未匯入成功的程式碼程式庫可繼續嘗試匯入。

遷移完成後，前往 Codeup 組織查看已遷移的程式碼程式庫和成員資訊，確認遷移結果。

Region 站支援的 Region 列表

說明

實際支援的 Region 以雲效控制台展示為準，以下列表僅供參考。

Region ID	地區
cn-shanghai	華東2（上海）
cn-hangzhou	華東1（杭州）
cn-beijing	華北2（北京）
cn-shenzhen	華南1（深圳）
ap-southeast-1	亞太地區東南1（新加坡）

常見問題

GitLab API 報 404 錯誤

將 import.source.apiEndpoint 改為帶 /api/v4 的地址，如 https://gitlab.example.com/api/v4。

複製失敗

檢查 import.source.localSSHKeyPath 配置，在本機執行 ssh -T git@<GitLab 主機> 測試 SSH 串連是否正常。

推送失敗

檢查目標 localSSHKeyPath 或 username/password 配置，以及目標平台是否已添加公開金鑰/帳號。

Token 無效

確認遷移 Token 已填入 import.target.accessKey，且具備程式碼程式庫、程式碼群組、組織成員、Webhook、保護分支、分支、成員等讀寫權限。

Region 站地址格式錯誤

確保 host 格式正確：https://{orgIdentifier}-{regionId}.devops.aliyuncs.com，其中 orgIdentifier 為組織標識（可在雲效組織管理後台查看），regionId 為地區 ID。

GitLab 庫角色	Codeup 庫角色
Owner/Maintainer	庫管理員
Developer	庫開發人員
Reporter/Guest	庫瀏覽者