将组织从 GitHub.com 迁移到 GitHub Enterprise Cloud

关于使用 GitHub Enterprise Importer

迁移组织

迁移到 GitHub Enterprise Cloud 包括 GitHub.com 上的帐户之间的迁移，以及迁移到企业的子域 GHE.com（如果要采用数据驻留）。

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

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

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

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

先决条件

强烈建议执行迁移的试运行，然后在不久之后完成生产迁移。若要了解试运行的详细信息，请参阅“在 GitHub 产品之间迁移的概述”。
确保了解将要迁移的数据以及导入程序已知的支持限制。有关详细信息，请参阅“关于 GitHub 产品之间的迁移”。
虽然并非必需，但建议在生产迁移期间停止工作。 Importer 不支持增量迁移，因此迁移期间发生的任何更改都不会迁移。如果选择在生产迁移期间不停止工作，需要手动迁移这些更改。
对于源组织，你必须是组织所有者或具有迁移者角色。有关详细信息，请参阅“管理 GitHub 产品之间迁移的访问权限”。
对于目标企业帐户，你必须是企业所有者。

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

要进行 GraphQL 查询，需要编写自己的脚本或使用 HTTP 客户端（如 Insomnia）。

若要详细了解 GitHub GraphQL API 入门（包括如何进行身份验证），请参阅“使用 GraphQL 建立调用”。

将所有 GraphQL 查询发送到迁移目标。**** 如果要迁移到具有数据驻留的 GitHub Enterprise Cloud，请确保将查询发送到 GHE.com 的企业子域的终结点。

步骤 1：获取迁移目标的企业 ID

作为 GitHub.com 中的企业所有者，使用以下查询返回要拥有已迁移组织的企业帐户的 ID。需要企业 ID 来识别迁移目标。

query(
  $slug: String!
){
  enterprise (slug: $slug)
  {
    slug
    id
  }
}

查询变量	说明
`slug`	企业帐户的数据域，可以通过查看企业的 URL（`https://github.com/enterprises/SLUG` 或 `https://SLUG.ghe.com`）来识别。

步骤 2：开始组织迁移

开始迁移时，单个组织及其随附的数据将迁移到你识别的目标企业中的全新组织。

mutation startOrganizationMigration (
  $sourceOrgUrl: URI!,
  $targetOrgName: String!,
  $targetEnterpriseId: ID!,
  $sourceAccessToken: String!,
    $targetAccessToken: String!
){
  startOrganizationMigration( input: {
    sourceOrgUrl: $sourceOrgUrl,
    targetOrgName: $targetOrgName,
    targetEnterpriseId: $targetEnterpriseId,
    sourceAccessToken: $sourceAccessToken,
        targetAccessToken: $targetAccessToken
  }) {
    orgMigration {
      id
    }
  }
}

查询变量	说明
`sourceOrgUrl`	源组织的 URL，例如 `https://github.com/octo-org`。
`targetOrgName`	希望新组织具有的名称。不能由目标平台上的另一个组织进行共享。
`targetEnterpriseId`	要在其中创建新组织的企业的 ID，由步骤 2 返回。
`sourceAccessToken`	源组织的 personal access token (classic)。有关要求，请参阅“管理 GitHub 产品之间迁移的访问权限”。
`targetAccessToken`	目标企业的 personal access token (classic)。

在下一步中，将使用从 startOrganizationMigration 突变返回的迁移 ID 来检查迁移状态。

步骤 3：检查迁移状态

若要检测任何迁移失败并确保迁移正常工作，可以使用 getMigration 查询查询已创建的 OrganizationMigration 以查看迁移状态。

查询将返回状态，告知迁移是 queued、in progress、failed 还是 completed，以及有关等待迁移的存储库数量的信息。如果迁移失败，Importer 将提供失败原因。

query (
  $id: ID!
){
  node( id: $id ) {
    ... on OrganizationMigration {
      id
            sourceOrgUrl
            targetOrgName
      state
      failure_reason
      remaining_repositories_count
      total_repositories_count
    }
  }
}

查询变量	说明
`id`	迁移的 `id`。

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

如果这是第一次迁移，需要安装 GEI extension of the GitHub CLI。有关 GitHub CLI 的详细信息，请参阅“关于 GitHub CLI”。

安装 GitHub CLI。有关 GitHub CLI 的安装说明，请参阅 GitHub CLI 存储库。

Note

需要 GitHub CLI 版本 2.4.0 或更高版本。可以使用 gh --version 命令检查已安装的版本。

安装 GEI extension。

Shell

gh extension install github/gh-gei

gh extension install github/gh-gei

每当需要 GEI extension 的帮助时，都可以将 --help 标志与命令一起使用。例如，gh gei --help 将列出所有可用命令，gh gei migrate-repo --help 将列出 migrate-repo 命令的所有可用选项。

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

GEI extension 每周更新一次。为了确保使用的是最新版本，请更新扩展。

gh extension upgrade github/gh-gei

步骤 3：设置环境变量

在使用 GEI extension 迁移到 GitHub Enterprise Cloud 之前，必须创建可以访问源组织和目标企业的 personal access tokens (classic)，然后将 personal access tokens (classic) 设置为环境变量。

创建并记录 personal access token，以满足对组织迁移的源组织进行身份验证的所有要求。有关详细信息，请参阅“管理 GitHub 产品之间迁移的访问权限”。
创建并记录 personal access token (classic)，以满足对组织迁移的目标企业进行身份验证的所有要求。
为 personal access tokens (classic) 设置环境变量，将以下命令中的 TOKEN 替换为上面记录的 personal access tokens (classic)。将 GH_PAT 用于目标企业，将 GH_SOURCE_PAT 用于源组织。
- 如果使用终端，请使用 export 命令。
  Shell
```
export GH_PAT="TOKEN"
export GH_SOURCE_PAT="TOKEN"
```
```
export GH_PAT="TOKEN"
export GH_SOURCE_PAT="TOKEN"
```
- 如果使用 PowerShell，请使用 $env 命令。
  Shell
```
$env:GH_PAT="TOKEN"
$env:GH_SOURCE_PAT="TOKEN"
```
```
$env:GH_PAT="TOKEN"
$env:GH_SOURCE_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：迁移组织

若要迁移组织，请使用 gh gei migrate-org 命令。

Shell

gh gei migrate-org --github-source-org SOURCE --github-target-org DESTINATION --github-target-enterprise ENTERPRISE

gh gei migrate-org --github-source-org SOURCE --github-target-org DESTINATION --github-target-enterprise ENTERPRISE

Note

如果要迁移到 GHE.com，请添加 --target-api-url TARGET-API-URL，其中 TARGET-API-URL 是企业的子域的基本 API URL。例如：https://api.octocorp.ghe.com。

将上述命令中的占位符替换为以下值。

占位符	值
源	源组织名称
DESTINATION	希望新组织具有的名称。不能由目标平台上的另一个组织进行共享。
ENTERPRISE	企业帐户的 slug，可以通过查看企业帐户的 URL（`https://github.com/enterprises/SLUG` 或 `https://SLUG.ghe.com`）来识别。

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

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

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

最后，建议对组织和迁移的存储库执行健全性检查。