使用 GitHub Enterprise Importer 对迁移进行故障排除

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

本文内容

关于 GitHub Enterprise Importer 的故障排除步骤

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

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

故障排除的第一步

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

  1. 验证您是否使用的是用于迁移的最新版本的 GitHub CLI 扩展。如果不是，请升级到最新版本。

  2. 验证您是否满足所有访问要求。有关更多信息，请参阅与您的迁移路径相关的文章。

  3. 尝试再次运行迁移。一些迁移问题是暂时的，第二次尝试可能会成功。

  4. 尝试在具有类似数据的不同存储库上运行迁移。这将有助于确定问题是特定于存储库还是代表更广泛的数据形状问题。

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

故障排除失败的迁移

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

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

无法运行迁移

如果您看到类似 No access to createMigrationMutation 或 Missing permissions 的错误，则您的个人帐户没有运行迁移所需的访问权限。请确保您是组织所有者，或已获得迁移者角色。有关授予迁移者角色的更多信息，请参阅 "关于 GitHub Enterprise Importer。"。

注意：如果您在 GitHub 产品之间迁移，请确保您是源组织和目标组织的组织所有者，或已获得迁移者角色。

资源受组织 SAML 强制保护

此错误表明您提供给 GitHub CLI 的个人访问令牌需要被授权用于 SAML 单点登录。有关更多信息，请参阅 "授权个人访问令牌用于 SAML 单点登录。"。

401 Unauthorized 响应

包含 401 状态码的错误通常表明您提供给 GitHub CLI 的个人访问令牌没有所需的范围。验证您提供的个人访问令牌的范围。有关所需范围的更多信息，请参阅与您的迁移路径相关的文章。

404 未找到 响应

包含 404 状态码的错误通常表示您的命令中存在拼写错误。请查看迁移日志以获取您输入的准确命令，并检查源代码库、组织或项目中的拼写错误。

归档生成失败 响应

如果您在从 GitHub Enterprise Server 迁移时收到 归档生成失败... 响应，则您的存储库可能太大。有关存储库大小限制的更多信息，请参阅“关于 GitHub 产品之间的迁移”。

首先，尝试使用 migrate-repo 命令的 --skip-releases 标志从迁移中排除发布。

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

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

密码名称不受支持 错误

如果您从 Bitbucket Server 迁移并收到类似 openssh 密钥文件密码名称 aes256-ctr 不受支持 的错误，则您的 SSH 私钥使用不受支持的密码。有关支持的密码的更多信息，请参阅“管理从 Bitbucket Server 迁移的访问权限”。

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

Shell
ssh-keygen -t ed25519 -Z aes256-cbc -C "[email protected]"

生成新的 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 Server 迁移并收到类似 Source export archive (/var/atlassian/application-data/bitbucket/shared/migration/export/Bitbucket_export_1.tar) does not exist 的错误，则 GitHub CLI 在您的 Bitbucket Server 实例上错误地查找迁移存档。

要解决此问题，请为 gh bbs2gh migrate-repo 设置 --bbs-shared-home 参数，指向您的 Bitbucket Server 或 Data Center 的共享主目录。默认的共享主目录是 /var/atlassian/application-data/bitbucket/shared，但您的配置可能有所不同。

您可以在 Bitbucket Server 中识别共享主目录。

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

如果您在具有多个节点的集群模式下运行 Bitbucket Data Center，则您的共享目录将在集群节点之间共享，并且应在每个节点上的相同位置挂载。

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 错误

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

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

了解迁移日志警告

即使您的迁移成功，您也应该查看迁移日志以检查警告。

迁移日志中的警告指向存储库中无法迁移的特定项目。有关更多信息，请参阅“访问您的 GitHub Enterprise Importer 迁移日志”。

注意：如果“迁移日志”问题在底部包含“迁移完成”，则存储库已迁移。警告仅表示存储库中的特定项目（例如拉取请求的评论）可能未正确迁移。

警告：“存储库元数据太大，无法迁移”

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

警告：“评论不在差异中”

如果您从 Azure DevOps 迁移，则拉取请求中从未更改过的行的拉取请求评论无法迁移到 GitHub。对于因这种原因而无法迁移的每条评论，您都会看到此警告。

注意：只有拉取请求中未更改过的行的评论会受到此限制的影响。拉取请求中已更改过的行的评论将被迁移。

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

警告：“拉取请求审查...由于 REVIEW_THREAD_MISSING_END_COMMIT_OID 错误而无法导入”

此警告出现在无法迁移拉取请求审查的地方，因为审查所附加的提交不再存在。

这通常发生在使用强制推送删除提交或删除分支的情况下。

在这种情况下，评论不会丢失，而是作为内联拉取请求评论迁移以保留历史记录，而不是作为附加到特定提交的审查。

组织迁移后团队引用失效

对团队的引用，例如 @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 支持。