关于使用 GitHub Enterprise Importer
进行存储库迁移
可以使用 GitHub CLI 或 API 运行迁移。
GitHub CLI 可简化迁移过程,建议大多数客户使用。 具有大量自定义需求的高级客户可以使用 API 构建自己的与 GitHub Enterprise Importer 的集成。
先决条件
- 强烈建议执行迁移的试运行,然后在不久之后完成生产迁移。 要了解试运行的详细信息,请参阅“从 Azure DevOps 迁移到 GitHub Enterprise Cloud 的概述”。
- 确保了解将要迁移的数据以及导入程序已知的支持限制。有关详细信息,请参阅“关于从 Azure DevOps 迁移到 GitHub Enterprise Cloud”。
- 虽然并非必需,但建议在生产迁移期间停止工作。 Importer 不支持增量迁移,因此迁移期间发生的任何更改都不会迁移。 如果选择在生产迁移期间不停止工作,需要手动迁移这些更改。
- 对于 GitHub 上的目标组织,你必须是组织所有者或拥有迁移者角色。 有关迁移者角色的详细信息,请参阅“管理从 Azure DevOps 迁移的访问权限”。
步骤 0:准备好使用 GitHub GraphQL API
要进行 GraphQL 查询,需要编写自己的脚本或使用 HTTP 客户端(如 Insomnia)。
要详细了解 GitHub GraphQL API 入门(包括如何进行身份验证),请参阅“使用 GraphQL 建立调用”。
将所有 GraphQL 查询发送到迁移目标。**** 如果要迁移到 具有数据驻留的 GitHub Enterprise Cloud,请确保将查询发送到 GHE.com 的企业子域的终结点。
步骤 1:获取迁移目标的 ownerId
作为 GitHub Enterprise Cloud 中的组织所有者,请使用 GetOrgInfo
查询为要拥有已迁移存储库的组织返回 ownerId
(也称为组织 ID)。 需要使用 ownerId
来标识迁移目标。
GetOrgInfo
查询
query(
$login: String!
){
organization (login: $login)
{
login
id
name
databaseId
}
}
查询变量 | 说明 |
---|---|
login | 组织名称。 |
GetOrgInfo
响应
{
"data": {
"organization": {
"login": "Octo",
"id": "MDEyOk9yZ2FuaXphdGlvbjU2MTA=",
"name": "Octo-org",
"databaseId": 5610
}
}
}
在此示例中,MDEyOk9yZ2FuaXphdGlvbjU2MTA=
是组织 ID 或 ownerId
,在下一步中会用到它。
步骤 2:确定要从何处迁移
可以使用 createMigrationSource
查询设置迁移源。 需要提供从 GetOrgInfo
查询收集的 ownerId
或组织 ID。
迁移源是 ADO 组织。
createMigrationSource
突变
mutation createMigrationSource($name: String!, $ownerId: ID!) {
createMigrationSource(input: {name: $name, url: "https://dev.azure.com", ownerId: $ownerId, type: AZURE_DEVOPS}) {
migrationSource {
id
name
url
type
}
}
}
Note
请确保对 type
使用 AZURE_DEVOPS
。
查询变量 | 说明 |
---|---|
name | 迁移源的名称。 此名称仅供你自己参考,因此可以使用任何字符串。 |
ownerId | GitHub Enterprise Cloud 上组织的组织 ID。 |
createMigrationSource
响应
{
"data": {
"createMigrationSource": {
"migrationSource": {
"id": "MS_kgDaACQxYmYxOWU4Yi0wNzZmLTQ3NTMtOTdkZC1hNGUzZmYxN2U2YzA",
"name": "Azure Devops Source",
"url": "https://dev.azure.com",
"type": "AZURE_DEVOPS"
}
}
}
}
在此示例中,MS_kgDaACQxYmYxOWU4Yi0wNzZmLTQ3NTMtOTdkZC1hNGUzZmYxN2U2YzA
是迁移源 ID,我们将在后面的步骤中使用。
步骤 3:开始迁移存储库
开始迁移时,单个存储库及其随附的数据将迁移到你标识的全新 GitHub 存储库。
如果要从同一源组织一次移动多个存储库,则可以将多个迁移排入队列。 最多可以同时运行 5 个存储库迁移。
startRepositoryMigration
突变
mutation startRepositoryMigration (
$sourceId: ID!,
$ownerId: ID!,
$sourceRepositoryUrl: URI!,
$repositoryName: String!,
$continueOnError: Boolean!,
$accessToken: String!,
$githubPat: String!,
$targetRepoVisibility: String!
){
startRepositoryMigration( input: {
sourceId: $sourceId,
ownerId: $ownerId,
repositoryName: $repositoryName,
continueOnError: $continueOnError,
accessToken: $accessToken,
githubPat: $githubPat,
targetRepoVisibility: $targetRepoVisibility
sourceRepositoryUrl: $sourceRepositoryUrl,
}) {
repositoryMigration {
id
migrationSource {
id
name
type
}
sourceUrl
}
}
}
查询变量 | 说明 |
---|---|
sourceId | 从 createMigrationSource 突变返回的迁移源 id 。 |
ownerId | 组织在 GitHub Enterprise Cloud 上的组织 ID。 |
repositoryName | 组织在 GitHub Enterprise Cloud 上拥有的任何存储库当前未使用的自定义唯一存储库名称。 迁移完成或停止时,将在此存储库中创建一个错误记录问题。 |
continueOnError | 迁移设置,允许在遇到不会导致迁移失败的错误时继续迁移。 必须为 true 或 false 。 强烈建议将 continueOnError 设置为 true ,以便继续迁移,除非 Importer 无法移动 Git 源,或 Importer 已断开连接且无法重新连接以完成迁移。 |
githubPat | 目标组织在 GitHub Enterprise Cloud 上的 personal access token。 |
accessToken | 源的 personal access token。 |
targetRepoVisibility | 新存储库的可见性。 必须为 private 、public 或 internal 。 如果未设置,则存储库将作为专用存储库迁移。 |
sourceRepositoryUrl | 源存储库的 URL,格式为 https://dev.azure.com/{organization}/{project}/_git/{repository} 。 |
有关 personal access token 要求的信息,请参阅“管理从 Azure DevOps 迁移的访问权限”。
在下一步中,将使用从 startRepositoryMigration
突变返回的迁移 ID 来检查迁移状态。
步骤 4:检查迁移状态
要检测任何迁移失败并确保迁移正常工作,可以使用 getMigration
查询检查迁移状态。 还可以使用 getMigrations
检查多个迁移的状态。
getMigration
查询将返回状态,让你知道迁移状态是 queued
、in progress
、failed
还是 completed
。 如果迁移失败,Importer 将提供失败原因。
getMigration
查询
query (
$id: ID!
){
node( id: $id ) {
... on Migration {
id
sourceUrl
migrationSource {
name
}
state
failureReason
}
}
}
查询变量 | 说明 |
---|---|
id | startRepositoryMigration 突变返回的迁移的 id 。 |
步骤 5:验证迁移并检查错误日志
要完成迁移,建议检查“迁移日志”问题。 此问题在目标存储库中的 GitHub 上创建。
最后,建议查看已迁移的存储库以进行完整性检查。
步骤 1:安装 ADO2GH extension of the GitHub CLI
如果这是首次迁移,需要安装 ADO2GH extension of the GitHub CLI。 有关 GitHub CLI 的详细信息,请参阅“关于 GitHub CLI”。
此外,也可以从 github/gh-ado2gh
存储库的版本页面下载一个独立的二进制文件。 可以直接运行此二进制文件,无需使用前缀 gh
。
-
安装 GitHub CLI。 有关 GitHub CLI 的安装说明,请参阅 GitHub CLI 存储库。
Note
需要 GitHub CLI 版本 2.4.0 或更高版本。 可以使用
gh --version
命令检查已安装的版本。 -
安装 ADO2GH extension。
Shell gh extension install github/gh-ado2gh
gh extension install github/gh-ado2gh
每当需要有关 ADO2GH extension 的帮助时,都可以将 --help
标志与命令一起使用。 例如,gh ado2gh --help
会列出所有可用命令,gh ado2gh migrate-repo --help
会列出 migrate-repo
命令的所有可用选项。
步骤 2:更新 ADO2GH extension of the GitHub CLI
ADO2GH extension of the GitHub CLI 每周更新一次。 为了确保使用的是最新版本,请更新扩展。
gh extension upgrade github/gh-ado2gh
gh extension upgrade github/gh-ado2gh
步骤 3:设置环境变量
在使用 ADO2GH extension 迁移到 GitHub Enterprise Cloud 之前,必须创建可以访问源和目标组织的 personal access token,然后将 personal access token 设置为环境变量。
-
创建并记录一个 personal access token (classic),用于在 GitHub Enterprise Cloud 上为目标组织进行身份验证,确保令牌满足所有要求。 有关详细信息,请参阅“管理从 Azure DevOps 迁移的访问权限”。
-
创建并记录一个 personal access token,用于对 Azure DevOps 上的源组织进行身份验证,确保此令牌满足所有要求。 有关详细信息,请参阅“管理从 Azure DevOps 迁移的访问权限”。
-
为 personal access token 设置环境变量,将以下命令中的 TOKEN 替换为上面记录的 personal access token。 将
GH_PAT
用于目标组织,并将ADO_PAT
用于源组织。-
如果使用终端,请使用
export
命令。Shell export GH_PAT="TOKEN" export ADO_PAT="TOKEN"
export GH_PAT="TOKEN" export ADO_PAT="TOKEN"
-
如果使用 PowerShell,请使用
$env
命令。Shell $env:GH_PAT="TOKEN" $env:ADO_PAT="TOKEN"
$env:GH_PAT="TOKEN" $env:ADO_PAT="TOKEN"
-
-
如果要迁移到 具有数据驻留的 GitHub Enterprise Cloud,为方便起见,请为企业的基 API URL 设置环境变量。**** 例如:
Shell export TARGET_API_URL="https://api.octocorp.ghe.com"
export TARGET_API_URL="https://api.octocorp.ghe.com"
在使用 GitHub CLI 运行的命令中,将此变量与
--target-api-url
选项一起使用。
步骤 4:生成迁移脚本
如果要一次性将多个存储库迁移到 GitHub Enterprise Cloud,请使用 GitHub CLI 生成迁移脚本。 生成的脚本将包含迁移命令的列表(每个存储库一个)。
如果要迁移单个存储库,请跳到下一步。
生成迁移脚本
若要生成迁移脚本,请运行 gh ado2gh generate-script
命令。
gh ado2gh generate-script --ado-org SOURCE --github-org DESTINATION --output FILENAME
gh ado2gh generate-script --ado-org SOURCE --github-org DESTINATION --output FILENAME
占位符
将上述命令中的占位符替换为以下值。
占位符 | 值 |
---|---|
源 | 源组织名称 |
目标 | 目标组织的名称 |
FILENAME | 生成的迁移脚本的文件名 如果使用终端,请使用 .ps1 文件扩展名,因为生成的脚本需要 PowerShell 才能运行。 可以安装适用于 Mac 或 Linux 的 PowerShell。 |
其他参数
Argument | 说明 |
---|---|
--target-api-url TARGET-API-URL | 如果要迁移到 GHE.com,请添加 --target-api-url TARGET-API-URL ,其中 TARGET-API-URL 是企业的子域的基本 API URL。 例如:https://api.octocorp.ghe.com 。 |
--all | 向脚本添加其他功能,例如重新连接管道、创建团队以及配置 Azure Boards 集成。 |
--download-migration-logs | 下载每个已迁移存储库的迁移日志。 有关迁移日志的详细信息,请参阅“访问 GitHub Enterprise Importer 的迁移日志”。 |
查看迁移脚本
生成脚本后,查看文件,并根据需要编辑脚本。
- 如果有任何不想迁移的存储库,请删除或注释禁止相应的行。
- 如果希望任何存储库在目标组织中具有不同的名称,请更新相应
--target-repo
标志的值。 - 如果要更改新存储库的可见性,请更新相应的
--target-repo-visibility
标志的值。 默认情况下,脚本设置与源存储库相同的可见性。
如果将 ADO2GH 作为一个独立的二进制文件而不是 GitHub CLI 的一个扩展下载,则需要更新所生成的脚本,以运行此二进制文件而不是 gh ado2gh
。
步骤 5:迁移存储库
可以使用迁移脚本迁移多个存储库,也可以使用 gh ado2gh migrate-repo
命令迁移单个存储库。
迁移多个存储库
要迁移多个存储库,请运行上面生成的脚本。 将以下命令中的 FILENAME 替换为生成脚本时提供的文件名。
-
如果使用终端,请使用
./
。Shell ./FILENAME
./FILENAME
-
如果使用 PowerShell,请使用
.\
。Shell .\FILENAME
.\FILENAME
迁移单个存储库
要迁移单个存储库,请使用 gh ado2gh migrate-repo
命令。
gh ado2gh migrate-repo --ado-org SOURCE --ado-team-project TEAM-PROJECT --ado-repo CURRENT-NAME --github-org DESTINATION --github-repo NEW-NAME
gh ado2gh migrate-repo --ado-org SOURCE --ado-team-project TEAM-PROJECT --ado-repo CURRENT-NAME --github-org DESTINATION --github-repo NEW-NAME
Note
如果要迁移到 GHE.com,请添加 --target-api-url TARGET-API-URL
,其中 TARGET-API-URL 是企业的子域的基本 API URL。 例如:https://api.octocorp.ghe.com
。
将上述命令中的占位符替换为以下值。
占位符 | 值 |
---|---|
源 | 源组织名称 |
CURRENT-NAME | 要迁移的存储库的名称 |
目标 | 目标组织的名称 |
NEW-NAME | 希望已迁移的存储库具有的名称 |
TEAM-PROJECT | 要迁移的存储库的团队项目的名称 |
如果要取消迁移,请使用 abort-migration
命令,将 MIGRATION-ID 替换为从 migrate-repo
返回的 ID。
gh ado2gh abort-migration --migration-id MIGRATION-ID
gh ado2gh abort-migration --migration-id MIGRATION-ID
步骤 6:验证迁移并检查错误日志
迁移完成后,建议查看迁移日志。 有关详细信息,请参阅“访问 GitHub Enterprise Importer 的迁移日志”。
建议查看已迁移的存储库以进行完整性检查。