在两个数据驻留企业之间迁移存储库

可以使用 GitHub Enterprise Importer （GEI） 扩展在 GitHub CLI 两个 带有数据驻留权的 GitHub Enterprise Cloud实例之间迁移存储库。

在本文中

关于数据驻留企业之间的迁移

两个数据驻留企业之间的迁移使用标准的 GEI 存档迁移流：

  1. GEI 连接到源 GHE.com 子域。
  2. GEI 生成包含存储库数据的存档。
  3. GEI 将存档上传到支持的迁移存储。
  4. GEI 在目标 GHE.com 子域上启动存储库迁移。
  5. 目标 Importer 下载并处理存档。

在此迁移过程中：

  • 源是子GHE.com域，例如https://SOURCE_SUBDOMAIN.ghe.com。
  • 目标是不同的GHE.com子域，例如https://DESTINATION_SUBDOMAIN.ghe.com。
  • 源和目标组织可以具有不同的名称。
  • 迁移的存储库可以在目标组织中具有不同的名称。

必须单独指定源和目标 API 终结点。 不要将目标 API URL 用于源操作。

重要

带有数据驻留权的 GitHub Enterprise Cloud API URL 使用格式 https://api.SUBDOMAIN.ghe.com。 这不同于 GitHub Enterprise Server API URL，它通常使用格式 https://HOSTNAME/api/v3。

先决条件

开始之前：

  • 确认源和目标是不同的 GHE.com 子域。
  • 在源组织和目标组织中，确保你是组织所有者或已被授予迁移者角色。
  • 为源组织创建一个 personal access token (classic) 。
  • 为目标组织创建一个 personal access token (classic) 。 有关所需范围，请参阅 管理 GitHub 产品之间迁移的访问权限。
  • 在执行生产迁移之前运行试用迁移。

建议在生产迁移期间暂时停止对源存储库的工作。 GitHub Enterprise Importer 不会执行增量迁移，因此不会自动包含迁移启动后所做的更改。

有关迁移的数据和已知限制的信息，请参阅 关于使用 GitHub Enterprise Importer 在 GitHub 产品之间迁移。

安装 GitHub CLI 和 GEI

安装GitHub CLI，然后安装 GEI 扩展程序：

Bash
gh extension install github/gh-gei

在开始迁移之前更新扩展：

Bash
gh extension upgrade github/gh-gei

若要显示可用选项，请执行以下操作：

Bash
gh gei migrate-repo --help

设置环境变量。

为这两家企业设置personal access token：

Bash
export GH_SOURCE_PAT="SOURCE_PERSONAL_ACCESS_TOKEN"
export GH_PAT="DESTINATION_PERSONAL_ACCESS_TOKEN"

为每个 GHE.com 子域设置 API URL：

Bash
export SOURCE_API_URL="https://api.SOURCE_SUBDOMAIN.ghe.com"
export TARGET_API_URL="https://api.DESTINATION_SUBDOMAIN.ghe.com"

将 DESTINATION_SUBDOMAIN 和 SOURCE_SUBDOMAIN 替换为源企业和目标企业的子域名。

例如：

Bash
export SOURCE_API_URL="https://api.source-example.ghe.com"
export TARGET_API_URL="https://api.destination-example.ghe.com"

令牌 GH_SOURCE_PAT 用于源端操作，包括存档生成。 令牌 GH_PAT 用于目标端操作。

配置存档 Blob 存储

GitHub Enterprise Importer 将每个项目导出到存档，然后将存档上传到可从中读取的 GitHub Blob 存储。 运行迁移时，可以选择存储后端：

存储选项如何选择它备注

GitHub-owned blob storage（推荐） | --use-github-storage | 无需设置。 GitHub 在成功迁移后或在迁移失败后的七天后自动删除存档。 AWS S3 | --aws-bucket-name（使用 AWS_REGION、AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY 环境变量，以及可选的 AWS_SESSION_TOKEN） | 你拥有存储桶及其生命周期的所有权。 GitHub 不会从存储中删除存档。 Azure Blob 存储 | AZURE_STORAGE_CONNECTION_STRING 环境变量（对于单个 migrate-repo 命令，可以改用 --azure-storage-connection-string） | 仅支持存储帐户访问密钥连接字符串（而不是 SAS）。 GitHub 不会从存储中删除存档。

迁移单个存储库

若要迁移单个存储库，请使用 gh gei migrate-repo 以下命令：

Bash
gh gei migrate-repo \
  --github-source-org SOURCE_ORGANIZATION \
  --source-repo SOURCE_REPOSITORY \
  --github-source-api-url "$SOURCE_API_URL" \
  --github-target-org DESTINATION_ORGANIZATION \
  --target-repo DESTINATION_REPOSITORY \
  --target-api-url "$TARGET_API_URL" \
  --verbose

将占位符替换为以下值：

占位符Description
SOURCE_ORGANIZATION在源企业中拥有存储库的组织。
SOURCE_REPOSITORY源组织中的存储库的名称。
DESTINATION_ORGANIZATION将在目标企业中拥有迁移后仓库的组织。
DESTINATION_REPOSITORY目标组织中的新存储库的名称。

例如：

Bash
gh gei migrate-repo \
  --github-source-org source-org \
  --source-repo example-repository \
  --github-source-api-url "$SOURCE_API_URL" \
  --github-target-org destination-org \
  --target-repo example-repository \
  --target-api-url "$TARGET_API_URL" \
  --verbose

如果省略 --target-repo，GEI 使用源存储库名称。

可选自变量

可以将以下选项添加到迁移命令：

论点Description
--target-repo-visibility TARGET-VISIBILITY设置新存储库的可见性。 支持的值是 private 和 internal。
--skip-releases在不发布的情况下迁移存储库。
--queue-only在不等待迁移完成的情况下对迁移进行排队。
--verbose显示其他迁移输出。

例如：

Bash
gh gei migrate-repo \
  --github-source-org source-org \
  --source-repo example-repository \
  --github-source-api-url "$SOURCE_API_URL" \
  --github-target-org destination-org \
  --target-repo example-repository \
  --target-api-url "$TARGET_API_URL" \
  --target-repo-visibility internal \
  --verbose

迁移多个存储库

对于多个存储库，请使用 gh gei generate-script。

Bash
gh gei generate-script \
  --github-source-org SOURCE_ORGANIZATION \
  --github-target-org DESTINATION_ORGANIZATION \
  --github-source-api-url "$SOURCE_API_URL" \
  --target-api-url "$TARGET_API_URL" \
  --output migration-script.ps1

运行脚本之前，请查看生成的脚本。 你可以：

  • 删除不应迁移的存储库。
  • 更改目标存储库名称。
  • 更改目标存储库可见性。
  • 添加诸如 --skip-releases 之类的选项。
  • 添加 --download-migration-logs 以下载每个迁移的日志。

使用 PowerShell 运行生成的脚本：

Bash
pwsh ./migration-script.ps1

检查迁移的状态

如果您使用 --queue-only 启动了迁移，请使用 GEI 输出的迁移 ID 来监控迁移状态：

Bash
gh gei wait-for-migration \
  --migration-id MIGRATION_ID \
  --target-api-url "$TARGET_API_URL" \
  --verbose

用 gh gei migrate-repo 返回的 ID 替换 MIGRATION_ID。

注意

检查时，请同时包含这两个 API URL 参数。 检索源端迁移信息和日志的 GEI 命令需要源 API URL。

下载迁移日志

若要下载迁移日志，请执行以下操作：

Bash
gh gei download-logs \
  --migration-id MIGRATION_ID \
  --github-source-api-url "$SOURCE_API_URL" \
  --target-api-url "$TARGET_API_URL"

即使迁移报告成功，也查看日志中的警告和错误。

中止迁移

中止排队或正在运行的迁移：

Bash
gh gei abort-migration \
  --migration-id MIGRATION_ID \
  --github-source-api-url "$SOURCE_API_URL" \
  --target-api-url "$TARGET_API_URL"

Troubleshooting

无法访问源租户

请确认：

  • --github-source-api-url 被设置为源子域。
  • URL 使用格式 https://api.SUBDOMAIN.ghe.com。
  • 源令牌存储在 GH_SOURCE_PAT.
  • 令牌有权访问源组织和存储库。

无法访问目标租户

请确认：

  • --target-api-url 设置为目标子域。
  • URL 使用格式 https://api.SUBDOMAIN.ghe.com。
  • 目标令牌存储在 GH_PAT.
  • 你有权在目标组织中创建存储库。

生成或上传存档时迁移失败

查看迁移输出和日志，然后验证：

  • 正确配置了迁移存档存储。
  • 存储提供程序可由迁移服务访问。
  • 迁移期间未修改源存储库。
  • 源和目标 API URL 尚未交换。

无法下载日志

使用 download-logs、wait-for-migration 或 abort-migration 时，请提供启动迁移时使用的相同源和目标 API URL：

--github-source-api-url "$SOURCE_API_URL" \
--target-api-url "$TARGET_API_URL"

源 URL 被拒绝

请确保使用 GHE.com 子域 API 终结点而不是 GitHub Enterprise Server 终结点。

使用：

https://api.SUBDOMAIN.ghe.com

请勿使用：

https://HOSTNAME/api/v3

/api/v3 格式适用于 GitHub Enterprise Server 源，但对于 带有数据驻留权的 GitHub Enterprise Cloud 而言并非正确的格式。