使用 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 单点登录一起使用。有关详细信息，请参阅授权个人访问令牌以用于单点登录。

401 Unauthorized 响应

包含 401 状态代码的失败通常表示你提供给 GitHub CLI 的个人访问令牌没有所需的范围。验证你提供的个人访问令牌上的范围。有关所需范围的详细信息，请参阅适用于你的迁移路径的相关文章。

404 Not Found 响应

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

Archive generation failed 响应

如果你从 GitHub Enterprise Server 迁移时收到 Archive generation failed... 响应，则你的存储库可能过大。有关存储库大小限制的详细信息，请参阅关于 GitHub 产品之间的迁移。

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

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

  1. 为你的存储库生成迁移存档。你一次只能导出一个存储库。有关说明，请参阅 GitHub Enterprise Server 文档中的从你的企业导出迁移数据。
  2. 将你的迁移存档上传到你选择的 blob 存储提供商。
  3. 为你的迁移存档生成一个可供 GitHub 访问的短期 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 私钥使用了不支持的密码。有关支持的密码的详细信息，请参阅管理 Bitbucket Server 迁移的访问权限。

要生成新的兼容 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 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 错误而无法导入”

当拉取请求审查无法迁移时，会发生此警告，因为审查所附的提交不再存在。

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

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

拉取请求审查作为内联拉取请求评论导入

这些警告表明拉取请求审查无法以其原始形式迁移，而是作为内联拉取请求评论

  • INVALID_REVIEW_THREAD
  • LINE_NOT_FOUND_IN_DIFF
  • REVIEW_THREAD_MISSING_BODY

组织迁移后团队引用损坏

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

© . This site is unofficial and not affiliated with GitHub, Inc.