跳到主要内容

将代码库从 GitHub.com 迁移到 GitHub Enterprise Cloud

您可以使用 GitHub CLI 或 GraphQL API 将代码库从 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 产品之间迁移概述”。
  • 确保您了解将要迁移的数据以及 Importer 的已知支持限制。有关更多信息,请参阅“关于在 GitHub 产品之间迁移”。
  • 虽然不是必需的,但我们建议在生产迁移期间停止工作。Importer 不支持增量迁移,因此迁移期间发生的任何更改都不会迁移。如果您选择不在生产迁移期间停止工作,则需要手动迁移这些更改。
  • 在源组织和目标组织中,您必须是组织所有者或被授予迁移者角色。有关更多信息,请参阅“管理在 GitHub 产品之间迁移的访问权限”。

步骤 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)。

您的迁移源是 GitHub.com 上的一个组织。

`createMigrationSource` 变异

mutation createMigrationSource($name: String!, $ownerId: ID!) {
  createMigrationSource(input: {name: $name, url: "https://github.com", ownerId: $ownerId, type: GITHUB_ARCHIVE}) {
    migrationSource {
      id
      name
      url
      type
    }
  }
}

注意

请确保将 `GITHUB_ARCHIVE` 用于 `type`。

查询变量描述
名称迁移源的名称。此名称仅供您自己参考,您可以使用任何字符串。
ownerId您在 GitHub Enterprise Cloud 上的组织的组织 ID。

`createMigrationSource` 响应

{
  "data": {
    "createMigrationSource": {
      "migrationSource": {
        "id": "MS_kgDaACQxYmYxOWU4Yi0wNzZmLTQ3NTMtOTdkZC1hNGUzZmYxN2U2YzA",
        "name": "GitHub.com Source",
        "url": "https://github.com",
        "type": "GITHUB_SOURCE"
      }
    }
  }
}

在此示例中,`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`,以便您的迁移将继续进行,除非导入程序无法移动 Git 源代码或导入程序已断开连接且无法重新连接以完成迁移。
githubPat您在 GitHub Enterprise Cloud 上的目标组织的个人访问令牌。
accessToken您的源的个人访问令牌。
targetRepoVisibility新仓库的可见性。必须为 `private`、`public` 或 `internal`。如果未设置,则您的仓库将作为私有仓库迁移。
sourceRepositoryUrl您的源仓库的 URL,格式为 `https://github.com/{organization}/{repository}`。

有关个人访问令牌要求,请参阅“在 GitHub 产品之间迁移的访问管理”。

在下一步中,您将使用 `startRepositoryMigration` 变异返回的迁移 ID 来检查迁移状态。

步骤 4:检查迁移状态

要检测任何迁移失败并确保您的迁移正常工作,您可以使用 `getMigration` 查询检查迁移状态。您还可以使用 `getMigrations` 检查多个迁移的状态。

`getMigration` 查询将返回一个状态,让您知道迁移是 `queued`(已排队)、`in progress`(正在进行)、`failed`(失败)还是 `completed`(已完成)。如果您的迁移失败,导入程序将提供失败原因。

`getMigration` 查询

query (
  $id: ID!
){
  node( id: $id ) {
    ... on Migration {
      id
      sourceUrl
      migrationSource {
        name
      }
      state
      failureReason
    }
  }
}
查询变量描述
id``startRepositoryMigration` 变异` 返回的迁移 `id`。

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

要完成迁移,我们建议您检查“迁移日志”问题。此问题是在 GitHub 的目标仓库中创建的。

Screenshot of an issue with the title "Migration Log." The second comment in the issue includes logs for a migration.

最后,我们建议您审查已迁移的仓库以进行完整性检查。

步骤 1:安装 GitHub CLI 的 GEI 扩展

如果这是您的第一次迁移,则需要安装 GitHub CLI 的 GEI 扩展。有关 GitHub CLI 的更多信息,请参阅“关于 GitHub CLI”。

或者,您可以从 发布页面 下载 `github/gh-gei` 仓库的独立二进制文件。您可以直接运行二进制文件,无需 `gh` 前缀。

  1. 安装 GitHub CLI。有关 GitHub CLI 的安装说明,请参阅 GitHub CLI 仓库

    注意

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

  2. 安装 GEI 扩展。

    Shell
    gh extension install github/gh-gei
    

任何时候,如果您需要 GEI 扩展的帮助,都可以对命令使用 `--help` 标志。例如,`gh gei --help` 将列出所有可用命令,而 `gh gei migrate-repo --help` 将列出 `migrate-repo` 命令可用的所有选项。

步骤 2:更新 GitHub CLI 的 GEI 扩展

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

gh extension upgrade github/gh-gei

步骤 3:设置环境变量

在您可以使用 GEI 扩展迁移到 GitHub Enterprise Cloud 之前,必须创建可以访问源组织和目标组织的个人访问令牌,然后将个人访问令牌设置为环境变量。

  1. 创建并记录一个将用于对 GitHub Enterprise Cloud 上的目标组织进行身份验证的个人访问令牌(经典),确保该令牌满足所有要求。有关更多信息,请参阅“在 GitHub 产品之间迁移的访问管理”。

  2. 创建并记录一个将用于对源组织进行身份验证的个人访问令牌,确保此令牌也满足所有相同的要求。

  3. 为个人访问令牌设置环境变量,在下面的命令中将 TOKEN 替换为您上面记录的个人访问令牌。对于目标组织,使用 `GH_PAT`;对于源组织,使用 `GH_SOURCE_PAT`。

    • 如果您使用的是 Terminal,请使用 `export` 命令。

      Shell
      export GH_PAT="TOKEN"
      export GH_SOURCE_PAT="TOKEN"
      
    • 如果您使用的是 PowerShell,请使用 `$env` 命令。

      Shell
      $env:GH_PAT="TOKEN"
      $env:GH_SOURCE_PAT="TOKEN"
      
  4. 如果您使用的是带有数据驻留的 GitHub Enterprise Cloud,为了方便起见,请为您的企业的 **基本 API URL** 设置一个环境变量。例如:

    Shell
    export TARGET_API_URL="https://api.octocorp.ghe.com"
    

    您将在使用 GitHub CLI 运行的命令中使用 `--target-api-url` 选项使用此变量。

步骤 4:生成迁移脚本

如果您想一次将多个仓库迁移到 GitHub Enterprise Cloud,请使用 GitHub CLI 生成迁移脚本。生成的脚本将包含迁移命令列表,每个仓库一个。

注意

生成脚本将输出一个 PowerShell 脚本。如果您使用的是 Terminal,则需要使用 `.ps1` 文件扩展名输出脚本,并为 MacLinux 安装 PowerShell 才能运行它。

如果您只想迁移单个仓库,请跳到下一步。

生成迁移脚本

要生成迁移脚本,请运行 `gh gei generate-script` 命令。

Shell
gh gei generate-script --github-source-org SOURCE --github-target-org DESTINATION --output FILENAME

如果您将 GEI 下载为独立二进制文件而不是 GitHub CLI 的扩展,则需要更新生成的脚本以运行二进制文件而不是 `gh gei`。

占位符

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

占位符
SOURCE源组织的名称
DESTINATION目标组织的名称
FILENAME生成的迁移脚本的文件名

如果您使用的是 Terminal,请使用 `.ps1` 文件扩展名,因为生成的脚本需要 PowerShell 才能运行。您可以为 MacLinux 安装 PowerShell。

附加参数

参数描述
--target-api-url TARGET-API-URL如果您迁移到 GHE.com,请添加 `--target-api-url TARGET-API-URL`,其中 TARGET-API-URL 是您企业子域的基本 API URL。例如:`https://api.octocorp.ghe.com`。
--download-migration-logs下载每个已迁移仓库的迁移日志。有关迁移日志的更多信息,请参阅“访问 GitHub Enterprise Importer 的迁移日志”。

查看迁移脚本

生成脚本后,请查看该文件,并可选择编辑该脚本。

  • 如果您不想迁移任何仓库,请删除或注释掉相应的行。
  • 如果您希望任何仓库在目标组织中具有不同的名称,请更新相应 `--target-repo` 标志的值。
  • 如果您想更改新仓库的可见性,请更新相应 `--target-repo-visibility` 标志的值。默认情况下,脚本设置与源仓库相同的可见性。

如果您的仓库的发布数据超过 10 GB,则无法迁移发布数据。使用 `--skip-releases` 标志迁移不包含发布数据的仓库。

如果您将 GEI 下载为独立二进制文件而不是 GitHub CLI 的扩展,则需要更新生成的脚本以运行二进制文件而不是 `gh gei`。

步骤 5:迁移仓库

您可以使用迁移脚本迁移多个仓库,也可以使用 `gh gei migrate-repo` 命令迁移单个仓库。

迁移多个仓库

要迁移多个仓库,请运行您上面生成的脚本。在下面的命令中,将 FILENAME 替换为您在生成脚本时提供的文件名。

  • 如果您使用的是 Terminal,请使用 `./`。

    Shell
    ./FILENAME
    
  • 如果您使用的是 PowerShell,请使用 `.\`。

    Shell
    .\FILENAME
    

迁移单个仓库

要迁移单个仓库,请使用 `gh gei migrate-repo` 命令。

Shell
gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME

占位符

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

占位符
SOURCE源组织的名称
CURRENT-NAME您要迁移的仓库的名称
DESTINATION目标组织的名称
NEW-NAME您希望迁移后的仓库具有的名称

附加参数

参数描述
--target-api-url TARGET-API-URL如果您迁移到 GHE.com,请添加 `--target-api-url TARGET-API-URL`,其中 TARGET-API-URL 是您企业子域的基本 API URL。例如:`https://api.octocorp.ghe.com`。
--skip-releases如果您的仓库的发布数据超过 10 GB,则无法迁移发布数据。使用 `--skip-releases` 标志迁移不包含发布数据的仓库。
--target-repo-visibility TARGET-VISIBILITY默认情况下,代码库迁移后可见性为私有。要设置可见性,您可以添加--target-repo-visibility标志,并指定privatepublicinternal。如果您迁移到具有托管用户的企业,则公共代码库不可用。

中止迁移

如果您想取消迁移,请使用abort-migration命令,并将MIGRATION-ID替换为migrate-repo返回的ID。

Shell
gh gei abort-migration --migration-id MIGRATION-ID

步骤 6:验证您的迁移并检查错误日志

迁移完成后,我们建议您查看迁移日志。更多信息,请参见“访问您的 GitHub Enterprise Importer 迁移日志”。

我们建议您检查已迁移的代码库,以确保其完整性。