使用 GitHub Enterprise Importer 迁移故障排除

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

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

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

故障排除的第一步

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

验证您是否正在使用用于迁移的最新版本的 GitHub CLI 扩展。如果不是，请升级到最新版本。
验证您是否满足所有访问要求。有关更多信息，请参阅您迁移路径的相关文章。
尝试重新运行迁移。一些迁移问题是暂时的，第二次尝试可能会成功。
尝试对具有相似数据的不同存储库运行迁移。这将有助于确定问题是存储库独有的，还是表示更广泛的数据形状问题。

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

迁移失败故障排除

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

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

无法运行迁移
资源受组织 SAML 强制保护
401 未授权 响应
404 未找到 响应
归档生成失败 响应
不支持的密码名称 错误
无法执行子系统“sftp” 错误
源导出存档...不存在 错误
发现存储库规则冲突 错误
您的推送将发布私人邮箱地址 错误

无法运行迁移

如果您看到类似于无法访问 createMigrationMutation 或缺少权限的错误，则您的个人帐户没有运行迁移所需的访问权限。确保您是组织所有者或已被授予迁移者角色。有关授予迁移者角色的更多信息，请参阅“关于 GitHub Enterprise Importer”。

注意

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

资源受组织 SAML 强制保护

此错误表示您提供给 GitHub CLI 的个人访问令牌需要授权才能与 SAML 单点登录一起使用。有关更多信息，请参阅“授权个人访问令牌与 SAML 单点登录一起使用”。

`401 未授权` 响应

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

`404 未找到`响应

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

`归档生成失败`响应

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

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

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

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

`不支持的密码名称`错误

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

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

Shell

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

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

生成新的 SSH 密钥对后，在可以使用该密钥之前，必须将公钥添加到 Bitbucket Server 实例的authorized_keys中。

`无法执行子系统“sftp”`错误

如果您是从 Bitbucket Server 迁移的，并且收到类似无法执行子系统“sftp”的错误，则表示您的服务器上未启用 SFTP 或您的用户帐户没有 SFTP 访问权限。

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

`源导出存档...不存在`错误

如果您是从 Bitbucket Server 迁移的，并且收到类似源导出存档 (/var/atlassian/application-data/bitbucket/shared/migration/export/Bitbucket_export_1.tar) 不存在的错误，则 GitHub CLI 正在 Bitbucket Server 实例的错误位置查找您的迁移存档。

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

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

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

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

`发现存储库规则冲突`错误

如果您收到发现存储库规则冲突错误，例如GH013: 发现 refs/heads/main 的存储库规则冲突，则源存储库中的数据与目标组织上配置的规则集冲突。有关更多信息，请参阅“关于规则集”。

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

`您的推送将发布私人电子邮件地址`错误

如果您收到包含GH007: 您的推送将发布私人电子邮件地址的Git 源迁移失败错误，则您尝试迁移的 Git 源包含由您已阻止推送到 GitHub 的电子邮件地址创作的提交。有关更多信息，请参阅“阻止公开个人电子邮件地址的命令行推送”。

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

了解迁移日志警告

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

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

注意

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

警告：“存储库元数据太大，无法迁移”
警告：“评论不在差异中”
警告：“拉取请求审查...由于 REVIEW_THREAD_MISSING_END_COMMIT_OID 错误而无法导入”
组织迁移后团队引用已损坏

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

如果您在“迁移日志”问题或 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 支持。

本文内容