将存储库从 Azure DevOps 迁移到 GitHub Enterprise Cloud

关于使用 GitHub Enterprise Importer

进行存储库迁移

可以使用 GitHub CLI 或 API 运行迁移。

GitHub CLI 可简化迁移过程，建议大多数客户使用。具有大量自定义需求的高级客户可以使用 API 构建自己的与 GitHub Enterprise Importer 的集成。

若要查看使用 GitHub CLI 的说明，请使用页面顶部的工具切换器。

Note

如果要迁移的存储库具有与传入存储库不匹配的规则集，则迁移将被阻止。若要绕过这些规则集并允许迁移，可以对目标组织中的所有部署密钥应用规则集绕过。

可以在组织级别设置存储库规则集。如果传入存储库与这些规则集中的任何一个都不匹配，则需要对每个规则集使用部署密钥绕过。请参阅“创建组织中存储库的规则集”。

先决条件

强烈建议执行迁移的试运行，然后在不久之后完成生产迁移。若要了解试运行的详细信息，请参阅“从 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 每周更新一次。为了确保使用的是最新版本，请更新扩展。

Shell

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 生成迁移脚本。生成的脚本将包含迁移命令的列表（每个存储库一个）。

Note

生成脚本会输出 PowerShell 脚本。如果使用的是终端，则需要以 .ps1 文件扩展名输出脚本，并安装适用于 Mac 或 Linux 的 PowerShell 才能运行它。

如果要迁移单个存储库，请跳到下一步。

生成迁移脚本

若要生成迁移脚本，请运行 gh ado2gh generate-script 命令。

Shell

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 命令。

Shell

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。

Shell

gh ado2gh abort-migration --migration-id MIGRATION-ID

gh ado2gh abort-migration --migration-id MIGRATION-ID

步骤 6：验证迁移并检查错误日志

迁移完成后，建议查看迁移日志。有关详细信息，请参阅“访问 GitHub Enterprise Importer 的迁移日志”。

建议查看已迁移的存储库以进行完整性检查。

将存储库从 Azure DevOps 迁移到 GitHub Enterprise Cloud

Tool navigation

本文内容

关于使用 GitHub Enterprise Importer

先决条件

步骤 0：准备好使用 GitHub GraphQL API

步骤 1：获取迁移目标的 `ownerId`

`GetOrgInfo` 查询

`GetOrgInfo` 响应

步骤 2：确定要从何处迁移

`createMigrationSource` 突变

`createMigrationSource` 响应

步骤 3：开始迁移存储库

`startRepositoryMigration` 突变

步骤 4：检查迁移状态

`getMigration` 查询

步骤 5：验证迁移并检查错误日志

步骤 1：安装 ADO2GH extension of the GitHub CLI

步骤 2：更新 ADO2GH extension of the GitHub CLI

步骤 3：设置环境变量

步骤 4：生成迁移脚本

生成迁移脚本

占位符

其他参数

查看迁移脚本

步骤 5：迁移存储库

迁移多个存储库

迁移单个存储库

步骤 6：验证迁移并检查错误日志