关于使用 GitHub Enterprise Importer 进行代码库迁移
迁移到 GitHub Enterprise Cloud 包括在 GitHub.com 上帐户之间的迁移,如果您采用数据驻留,则包括迁移到贵企业在 GHE.com 上的子域。
您可以使用 GitHub CLI 或 API 运行迁移。
GitHub CLI 简化了迁移过程,建议大多数客户使用。具有大量自定义需求的高级客户可以使用 API 来构建他们自己的 GitHub Enterprise Importer 集成。
先决条件
- 我们强烈建议您进行试运行迁移,并在之后立即完成生产迁移。要了解有关试运行的更多信息,请参阅“在 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 的目标仓库中创建的。
最后,我们建议您审查已迁移的仓库以进行完整性检查。
步骤 1:安装 GitHub CLI 的 GEI 扩展
如果这是您的第一次迁移,则需要安装 GitHub CLI 的 GEI 扩展。有关 GitHub CLI 的更多信息,请参阅“关于 GitHub CLI”。
或者,您可以从 发布页面 下载 `github/gh-gei` 仓库的独立二进制文件。您可以直接运行二进制文件,无需 `gh` 前缀。
-
安装 GitHub CLI。有关 GitHub CLI 的安装说明,请参阅 GitHub CLI 仓库。
注意
您需要 2.4.0 或更高版本的 GitHub CLI。您可以使用 `gh --version` 命令检查已安装的版本。
-
安装 GEI 扩展。
Shell gh extension install github/gh-gei
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 之前,必须创建可以访问源组织和目标组织的个人访问令牌,然后将个人访问令牌设置为环境变量。
-
创建并记录一个将用于对 GitHub Enterprise Cloud 上的目标组织进行身份验证的个人访问令牌(经典),确保该令牌满足所有要求。有关更多信息,请参阅“在 GitHub 产品之间迁移的访问管理”。
-
创建并记录一个将用于对源组织进行身份验证的个人访问令牌,确保此令牌也满足所有相同的要求。
-
为个人访问令牌设置环境变量,在下面的命令中将 TOKEN 替换为您上面记录的个人访问令牌。对于目标组织,使用 `GH_PAT`;对于源组织,使用 `GH_SOURCE_PAT`。
-
如果您使用的是 Terminal,请使用 `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:生成迁移脚本
如果您想一次将多个仓库迁移到 GitHub Enterprise Cloud,请使用 GitHub CLI 生成迁移脚本。生成的脚本将包含迁移命令列表,每个仓库一个。
注意
生成脚本将输出一个 PowerShell 脚本。如果您使用的是 Terminal,则需要使用 `.ps1` 文件扩展名输出脚本,并为 Mac 或 Linux 安装 PowerShell 才能运行它。
如果您只想迁移单个仓库,请跳到下一步。
生成迁移脚本
要生成迁移脚本,请运行 `gh gei generate-script` 命令。
gh gei generate-script --github-source-org SOURCE --github-target-org DESTINATION --output FILENAME
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 才能运行。您可以为 Mac 或 Linux 安装 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
./FILENAME
-
如果您使用的是 PowerShell,请使用 `.\`。
Shell .\FILENAME
.\FILENAME
迁移单个仓库
要迁移单个仓库,请使用 `gh gei migrate-repo` 命令。
gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME
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 标志,并指定private 、public 或internal 。如果您迁移到具有托管用户的企业,则公共代码库不可用。 |
中止迁移
如果您想取消迁移,请使用abort-migration
命令,并将MIGRATION-ID替换为migrate-repo
返回的ID。
gh gei abort-migration --migration-id MIGRATION-ID
gh gei abort-migration --migration-id MIGRATION-ID
步骤 6:验证您的迁移并检查错误日志
迁移完成后,我们建议您查看迁移日志。更多信息,请参见“访问您的 GitHub Enterprise Importer 迁移日志”。
我们建议您检查已迁移的代码库,以确保其完整性。