关于使用 GitHub Enterprise Importer
迁移组织
可以使用 GitHub CLI 或 API 运行迁移。
GitHub CLI 可简化迁移过程,建议大多数客户使用。 具有大量自定义需求的高级客户可以使用 API 构建自己的与 GitHub Enterprise Importer 的集成。
先决条件
- 强烈建议执行迁移的试运行,然后在不久之后完成生产迁移。 要了解试运行的详细信息,请参阅“在 GitHub 产品之间迁移的概述”。
- 确保了解将要迁移的数据以及导入程序已知的支持限制。有关详细信息,请参阅“关于 GitHub 产品之间的迁移”。
- 虽然并非必需,但建议在生产迁移期间停止工作。 Importer 不支持增量迁移,因此迁移期间发生的任何更改都不会迁移。 如果选择在生产迁移期间不停止工作,需要手动迁移这些更改。
- 对于源组织,你必须是组织所有者或具有迁移者角色。 有关详细信息,请参阅“管理 GitHub 产品之间迁移的访问权限”。
- 对于目标企业帐户,你必须是企业所有者。
步骤 0:准备好使用 GitHub GraphQL API
要进行 GraphQL 查询,需要编写自己的脚本或使用 HTTP 客户端(如 Insomnia)。
要详细了解 GitHub GraphQL API 入门(包括如何进行身份验证),请参阅“使用 GraphQL 建立调用”。
步骤 1:获取迁移目标的企业 ID
作为 GitHub.com 中的企业所有者,使用以下查询返回要拥有已迁移组织的企业帐户的 ID。 需要企业 ID 来识别迁移目标。
query(
$slug: String!
){
enterprise (slug: $slug)
{
slug
id
}
}
查询变量 | 说明 |
---|---|
slug | 企业帐户的 slug,可以通过查看企业的 URL (https://github.com/enterprises/SLUG ) 来识别。 |
步骤 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 | 希望新组织具有的名称。 在 GitHub.com 上必须是唯一的。 |
targetEnterpriseId | 要在其中创建新组织的企业的 ID,由步骤 2 返回。 |
sourceAccessToken | 源组织的 personal access token。 有关要求,请参阅“管理 GitHub 产品之间迁移的访问权限”。 |
targetAccessToken | 目标企业的 personal access token。 |
在下一步中,将使用从 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 存储库。
注意:需要 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,然后将 personal access tokens 设置为环境变量。
-
创建并记录 personal access token,以满足对组织迁移的源组织进行身份验证的所有要求。 有关详细信息,请参阅“管理 GitHub 产品之间迁移的访问权限”。
-
创建并记录 personal access token,以满足对组织迁移的目标企业进行身份验证的所有要求。
-
为 personal access tokens 设置环境变量,将以下命令中的 TOKEN 替换为上面记录的 personal access tokens。 将
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"
-
步骤 4:迁移组织
若要迁移组织,请使用 gh gei migrate-org
命令。
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
将上述命令中的占位符替换为以下值。
占位符 | 值 |
---|---|
源 | 源组织名称 |
DESTINATION | 希望新组织具有的名称。 在 GitHub.com 上必须是唯一的。 |
ENTERPRISE | 企业帐户的 slug,可以通过查看企业帐户的 URL (https://github.com/enterprises/SLUG ) 来识别。 |
步骤 5:验证迁移并检查错误日志
迁移完成后,建议检查迁移日志存储库。 有关详细信息,请参阅“访问 GitHub Enterprise Importer 的迁移日志”。
最后,建议对组织和迁移的存储库执行健全性检查。