使用 GitHub Enterprise Importer 排查迁移问题

本文内容

如果迁移失败或产生意外结果，可以尝试常见的故障排除步骤。

关于 GitHub Enterprise Importer

的故障排除步骤

如果迁移失败或产生意外结果，请尝试以下故障排除的前几个步骤，这通常会解决各种问题。 如果前几个步骤无法解决问题，检查迁移日志中的错误消息。 然后，找到本文中的错误消息，并尝试执行解决步骤。

如果在尝试针对错误消息的故障排除步骤后无法解决问题，可以联系 GitHub 支持。

故障排除的前几个步骤

在进一步调查之前，请尝试这些故障排除步骤，它们通常能解决各种问题。

  1. 验证是否正在使用最新版本的 GitHub CLI 扩展进行迁移。 如果不是，请升级到最新版本。
  2. 验证是否满足所有访问要求。 有关详细信息，请参阅“管理 GitHub Enterprise Importer 的访问权限”。
  3. 尝试再次运行迁移。 某些迁移问题是暂时性的，第二次尝试可能会成功。
  4. 尝试在具有类似数据的其他存储库上运行迁移。 这将有助于确定问题是存储库独有的，还是代表更广泛的数据形状问题。

如果这些步骤无法解决问题，请查看迁移日志中的错误消息。 需要检查的日志将取决于迁移是失败还是成功。

排查失败迁移的问题

如果迁移失败，请查看 GitHub CLI 为每次迁移生成的详细日志条目。 日志文件保存在运行迁移的同一目录中。

该日志包含你发出的每个命令以及 GitHub CLI 在响应中发出的所有 API 请求的记录。 失败和错误消息通常显示在日志末尾。

无法运行迁移

如果看到错误（如 No access to createMigrationMutation 或 Missing permissions），个人帐户没有运行迁移所需的访问权限。 确保你是组织所有者或已被授予迁移者角色。 有关授予迁移者角色的详细信息，请参阅“使用 GitHub Enterprise Importer 迁移存储库”。

注意：如果要在 GitHub 产品之间进行迁移，请确保你是组织所有者或已被授予源组织和目标组织的迁移者角色。

资源受组织 SAML 强制措施保护

此错误指示向 GitHub CLI 提供的 personal access token 需要获得与 SAML 单一登录配合使用的授权。 有关详细信息，请参阅“授权用于 SAML 单点登录的个人访问令牌”。

401 Unauthorized 响应

包含 401 状态代码的故障通常表示提供给 GitHub CLI 的 personal access token 没有所需的范围。 验证为源组织和目标组织提供的 personal access token 上的范围。 有关所要求范围的详细信息，请参阅“管理 GitHub Enterprise Importer 的访问权限”。

404 Not Found 响应

包含 404 状态代码的故障通常表示某个命令中存在拼写错误。 查看迁移日志中输入的确切命令，检查源存储库、组织或项目中的拼写错误。

Archive generation failed 响应

如果在从 GitHub Enterprise Server 迁移时收到 Archive generation failed... 响应，则存储库可能太大。 有关存储库大小限制的详细信息，请参阅“GitHub Enterprise Importer 的迁移支持”。

首先，通过将 --skip-releases 标志与 migrate-repo 命令配合使用，尝试从迁移中排除发行版。

如果这不起作用，建议升级到 GitHub Enterprise Server 3.8.0 或更高版本。 如果无法升级，另一选项是使用 ghe-migrator 手动生成存储库存档：

  1. 为存储库生成迁移存档。 一次只能导出一个存储库。 有关说明，请参阅 GitHub Enterprise Server 文档中的“从企业导出迁移数据”。
  2. 将迁移存档上传到所选的 Blob 存储提供程序。
  3. 为迁移存档生成可供 GitHub.com 访问的短期 URL，例如 AWS S3 预签名 URL 或 Azure Blob 存储 SAS URL。
  4. 调用 migrate-repo 命令，并将 --git-archive-url 和 --metadata-archive-url 标志都设置为上一步中存档的 URL。

cipher name is not supported 个错误

如果要从 Bitbucket Server 迁移，并在运行迁移时收到类似 cipher name aes256-ctr for openssh key file is not supported 的错误，则 SSH 私钥使用了不受支持的密码。 有关受支持密码的详细信息，请参阅“管理 GitHub Enterprise Importer 的访问权限”。

要生成新的兼容 SSH 密钥对，请运行以下命令：

Shell
ssh-keygen -t ed25519 -Z aes256-cbc -C "your_email@example.com"

生成新的 SSH 密钥对后，必须先将公钥添加到 Bitbucket Server 实例的 authorized_keys，然后才能使用该密钥。

Subsystem 'sftp' could not be executed 个错误

如果要从 Bitbucket Server 迁移并收到类似 Subsystem 'sftp' could not be executed 的错误，则服务器上未启用 SFTP，或者用户帐户没有 SFTP 访问权限。

应联系服务器管理员，并要求他们为用户帐户启用 SFTP 访问权限。

Source export archive... does not exist 个错误

如果要从 Bitbucket 服务器迁移，但收到类似 Source export archive (/var/atlassian/application-data/bitbucket/shared/migration/export/Bitbucket_export_1.tar) does not exist 的错误，GitHub CLI 在 Bitbucket 服务器实例的错误位置查找迁移存档。

若要解决此问题，请将 gh bbs2gh migrate-repo 的 --bbs-shared-home 参数设置为 Bitbucket 服务器或数据中心的共享主目录。 默认共享主目录为 /var/atlassian/application-data/bitbucket/shared，但配置可能有所不同。

可以在 Bitbucket 服务器中标识共享的主目录。

  1. 导航到 Bitbucket 服务器或数据中心实例的管理区域。
  2. 在边栏的“系统”下，单击“存储”。
  3. 在“共享目录”下，查看服务器的共享主目录的位置。

如果在具有多个笔记的群集模式下运行 Bitbucket 数据中心，则共享目录将在群集节点之间共享，并且应装载在每个节点上的同一位置。

Repository rule violations found 个错误

如果收到 Repository rule violations found 错误（如 GH013: Repository rule violations found for refs/heads/main），则表示源存储库中的数据与目标组织上配置的规则集冲突。 有关详细信息，请参阅“关于规则集”。

可以在迁移期间暂时禁用规则集，也可以使用绕过模式或绕过列表从配置的规则中豁免你的迁移。 有关详细信息，请参阅“管理组织中存储库的规则集”。

Your push would publish a private email address 个错误

如果收到包含 GH007: Your push would publish a private email address 的 Git source migration failed 错误，则尝试迁移的 Git 源包括由电子邮件地址创作的提交，你已阻止将这些提交推送到 GitHub。 有关详细信息，请参阅 GitHub Enterprise Cloud 文档中的“阻止会暴露个人电子邮件地址的命令行推送”。

若要解决此错误，可以重写 Git 历史记录以删除电子邮件地址，也可以禁用“阻止公开我的电子邮件的命令行推送”设置。

排查成功迁移的问题

如果迁移成功但产生意外结果，请查看迁移日志中的错误消息。 有关详细信息，请参阅“访问 GitHub Enterprise Importer 的迁移日志”。

注意：如果“迁移日志”问题在底部包含“迁移已完成”，则表明已迁移存储库。 错误消息仅指示存储库中的特定项（例如对拉取请求的注释）可能未正确迁移。

存储库元数据太大，无法迁移

如果在“迁移日志”问题或 GitHub CLI 中看到“存储库元数据太大，无法迁移”，则存储库超过了 10 GB 的最大存档大小。 这通常是由大型的发行版资产引起的。 尝试使用 migrate-repo 命令的 --skip-releases 标志从迁移中排除发行版。

注释无差异

如果要从 Azure DevOps 迁移，拉取请求中从未更改过的行的拉取请求注释无法迁移到 GitHub。 对于由于此原因而无法迁移的每个注释，你都将看到此警告。

注意：只有拉取请求中未更改的行的注释才会受此限制的影响。 迁移拉取请求中已更改的行的注释。

请注意，受影响的注释不会出现在已迁移的存储库中，但这些警告不需要你进一步操作。

拉取请求审查线程未在拉取请求中迁移

此警告是“注释无差异”的一种更通用的形式。 如果看到此警告，则无法迁移拉取请求中文件的注释，原因与上述原因不同。 大多数情况下，注释位于拉取请求历史记录中某个时间点已更改的行上，但随后拉取请求发生了更改，因此情况不再如此。

  • 注释针对的是拉取请求历史记录中之后已删除的文件。
  • 注释针对的是拉取请求历史记录中某个时间点已更改的代码，但作者后来决定删除更改。
  • 拉取请求被 Squash 合并到单个提交中，这会阻止 GitHub 正确构造拉取请求历史记录以正确放置注释。

此问题对已关闭拉取请求的影响最常见。

请注意，受影响的注释不会出现在已迁移的存储库中，但这些警告不需要你进一步操作。

组织迁移后，团队引用中断

对团队的引用（例如 @octo-org/octo-team）不会在组织迁移的过程中更新。 这可能会导致目标组织出现问题，例如 CODEOWNERS 文件未按预期工作。

可以在迁移后更新这些引用，也可以通过重命名源组织来保留团队名称，以便为目标组织使用原始名称。

例如，如果源组织为 @octo-org，并且 CODEOWNERS 文件包含对团队 @octo-org/octo-team 的引用，则可以在迁移之前将源组织重命名为 @octo-org-temp，从而允许使用 @octo-org 作为新组织的名称。 然后，迁移团队将被称为 @octo-org/octo-team，已迁移的存储库中的 CODEOWNERS 文件将按预期工作。

锁定的存储库

迁移后，你可能会发现源或目标存储库已锁定，禁用了对存储库代码及其所有资源（例如问题和拉取请求）的访问。 有关锁定的存储库的详细信息，请参阅“关于锁定的存储库”。

解锁存储库的过程取决于存储存储库的 GitHub 产品。

  • 如果锁定的存储库位于 GitHub Enterprise Server 上，则站点管理员可以使用站点管理员仪表板解锁存储库。 有关详细信息，请参阅 GitHub Enterprise Server 文档中的“锁定存储库"
  • 如果锁定的存储库位于 GitHub.com 上，则可以联系 GitHub 支持 来解锁存储库。

注意：如果迁移失败，并非所有数据都已迁移。 如果选择解锁并使用存储库，则会丢失数据。 删除锁定的存储库并重试迁移可能是更好的选择。

联系 GitHub 支持

如果在尝试上述故障排除步骤后仍无法解决问题，可以通过 GitHub 支持门户 联系 GitHub 支持。