Skip to main content
我们经常发布文档更新,此页面的翻译可能仍在进行中。 有关最新信息,请访问英语文档

Migrating organizations from GitHub.com to GitHub Enterprise Cloud

You can migrate organizations from GitHub.com to GitHub Enterprise Cloud, using the GitHub CLI or the GraphQL API.

注意:GitHub Enterprise Importer 目前为公共 beta 版,可能会有所变化。

About organization migrations with GitHub Enterprise Importer

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

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

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

Prerequisites

  • To ensure you understand the known support limitations of the Importer, review "关于 GitHub Enterprise Importer."
  • 强烈建议执行迁移的试运行,然后在不久之后完成生产迁移。 若要详细了解试运行最佳做法,请参阅“准备使用 GitHub Enterprise Importer 运行迁移”。
  • 虽然并非必需,但建议在生产迁移期间停止工作。 Importer 不支持增量迁移,因此迁移期间发生的任何更改都不会迁移。 如果选择在生产迁移期间不停止工作,需要手动迁移这些更改。
  • For the source organization, you must be an organization owner or have the migrator role. For more information, see "为 GitHub Enterprise Importer 授予迁移者角色."
  • For the destination enterprise account, you must be an enterprise owner.

Step 0: Get ready to use the GitHub GraphQL API

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

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

Step 1: Get the enterprise ID for your migration destination

As an enterprise owner in GitHub.com, use the following query to return the ID for the enterprise account you want to own the migrated organization. You'll need the enterprise ID to identify your migration destination.

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

Query variableDescription
slugThe slug for your enterprise account, which you can identify by looking at the URL for your enterprise, https://github.com/enterprises/SLUG.

Step 2: Start your organization migration

When you start a migration, a single organization and its accompanying data migrates into a brand new organization within the destination enterprise that you identify.

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
    }
  }
}
Query variableDescription
sourceOrgUrlThe URL of the source organization, such as https://github.com/octo-org.
targetOrgNameThe name you want the new organization to have. Must be unique on GitHub.com.
targetEnterpriseIdThe ID of the enterprise that you want to create the new organization in, returned by step 2.
sourceAccessTokenYour personal access token for the source organization. For requirements, see "管理 GitHub Enterprise Importer 的访问权限."
targetAccessTokenYour personal access token for the destination enterprise.

In the next step, you'll use the migration ID returned from the startOrganizationMigration mutation to check the migration status.

Step 3: Check the status of your migration

To detect any migration failures and ensure your migration is working, you can query the OrganizationMigration(s) that you have created to see the migration status using the getMigration query.

The query will return with a status to let you know if the migration is queued, in progress, failed, or completed, plus information about how many repositories are waiting to be migrated. If your migration failed, the Importer will provide a reason for the failure.

query (
  $id: ID!
){
  node( id: $id ) {
    ... on OrganizationMigration {
      id
			sourceOrgUrl
			targetOrgName
      state
      failure_reason
      remaining_repositories_count
      total_repositories_count
    }
  }
}
Query variableDescription
idThe id of your migration.

Step 1: Install the GEI extension of the GitHub CLI

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

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

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

  2. 安装 GEI extension。

    Shell
    gh extension install github/gh-gei

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

Step 2: Update the GEI extension of the GitHub CLI

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

gh extension upgrade github/gh-gei

Step 3: Set environment variables

Before you can use the GEI extension to migrate to GitHub Enterprise Cloud, you must create personal access tokens that can access the source organization and destination enterprise, then set the personal access tokens as environment variables.

  1. Create and record a personal access token that meets all the requirements to authenticate for the source organization for organization migrations. For more information, see "管理 GitHub Enterprise Importer 的访问权限."

  2. Create and record a personal access token that meets all the requirements to authenticate for the destination enterprise for organization migrations.

  3. Set environment variables for the personal access tokens, replacing TOKEN in the commands below with the personal access tokens you recorded above. Use GH_PAT for the destination enterprise and GH_SOURCE_PAT for the source organization.

    • If you're using Terminal, use the export command.

      Shell
      export GH_PAT="TOKEN"
      export GH_SOURCE_PAT="TOKEN"
    • If you're using PowerShell, use the $env command.

      Shell
      $env:GH_PAT="TOKEN"
      $env:GH_SOURCE_PAT="TOKEN"

Step 4: Migrate your organization

To migrate an organization, use the gh gei migrate-org command.

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

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

占位符
源组织名称
DESTINATIONThe name you want the new organization to have. Must be unique on GitHub.com.
ENTERPRISEThe slug for your destination enterprise, which you can identify by looking at the URL for your enterprise account, https://github.com/enterprises/SLUG.

Step 5: Validate your migration and check the error log

After your migration has finished, we recommend that you check the migration log repository. For more information, see "访问 GitHub Enterprise Importer 的迁移日志."

Finally, we recommend you perform a soundness check of your organization and migrated repositories.