Enterprise Server 3.22 目前作为发布候选版本提供。

使用 GitHub Enterprise Importer 排查迁移中的问题

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

在本文中

关于故障排除步骤 GitHub Enterprise Importer

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

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

故障排除的前几个步骤

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

  1. 请确认您正在使用的用于迁移的 GitHub CLI 扩展是最新版本。 如果不是，请升级到最新版本。

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

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

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

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

解决失败迁移问题

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

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

无法运行迁移

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

注意

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

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

此错误表示你提供给 personal access token 的 GitHub CLI 需要被授权用于 SAML 单点登录。 有关详细信息，请参阅“授权个人访问令牌以与单点登录一起使用”。

401 Unauthorized 响应

包含 401 状态代码的失败通常表示你提供给 personal access token 的 GitHub CLI 未具备所需权限范围。 请验证personal access token上的你提供的作用域。 有关所需作用域的详细信息，请参阅迁移路径的相应文章。

404 Not Found 响应

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

Archive generation failed 响应

如果在从Archive generation failed...迁移时收到GitHub Enterprise Server响应，则说明您的存储库可能太大。 有关存储库大小限制的详细信息，请参阅“关于使用 GitHub Enterprise Importer 在 GitHub 产品之间迁移”。

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

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

  1. 为存储库生成迁移存档。 一次只能导出一个存储库。 有关说明，请参阅 从企业导出迁移数据。
  2. 将迁移存档上传到所选的 Blob 存储提供程序。
  3. 为你的迁移归档生成一个短期有效 URL，该 URL 可被 GitHub 访问，例如 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 服务器进行迁移，并收到类似的 Source export archive (/var/atlassian/application-data/bitbucket/shared/migration/export/Bitbucket_export_1.tar) does not exist 错误，这意味着 GitHub CLI 正在 Bitbucket 服务器实例上错误的位置查找你的迁移存档。

若要解决此问题，请将 --bbs-shared-home 的 gh bbs2gh migrate-repo 参数设置为 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 错误

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

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

理解迁移日志警告

即使迁移成功仍应查看迁移日志，检查是否存在警告。

迁移日志中的警告指向存储库中无法迁移的具体项目。 有关详细信息，请参阅“访问 GitHub Enterprise Importer 的迁移日志”。

注意

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

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

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

警告：“注释无差异”

如果你从 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.com，可以联系 以解锁存储库。

注意

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

联系 GitHub 支持

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