管理从 Bitbucket Server 迁移的访问权限

在使用 GitHub Enterprise Importer 之前，请确保您对迁移的源和目标具有适当的访问权限。

本文内容

关于 GitHub Enterprise Importer 的必需访问权限

为了保护您的数据，GitHub 强制执行使用 GitHub Enterprise Importer 的特定访问权限要求。这些要求根据您尝试执行的任务而有所不同。为避免错误，您应仔细阅读本文，并验证您满足要完成的任务的所有要求。

要将存储库从 Bitbucket Server 迁移到 GitHub，您需要对源（您的 Bitbucket Server 实例）和目标（GitHub 上的组织）有足够的访问权限。要拥有足够的访问权限，您需要所有以下内容。

  • 在 GitHub 上的目标组织中必需的角色
  • 可以访问 GitHub 上目标组织的个人访问令牌
    • 个人访问令牌必须具有所有必需的范围，这些范围取决于您的角色和您要完成的任务。
    • 如果目标组织对 GitHub 使用 SAML 单点登录，则您必须授权个人访问令牌进行 SSO。
  • 在 Bitbucket Server 上，必需的权限和 SFTP 或 SMB 访问

此外，如果您在目标组织中使用 IP 允许列表，您可能需要配置允许列表以允许 GitHub Enterprise Importer 访问。

关于迁移角色

为了消除组织所有者完成迁移的需要，GitHub.com 包含一个用于使用 GitHub Enterprise Importer 的独特角色。授予迁移角色允许您指定其他团队或个人来处理您的迁移。您只能为 GitHub.com 上的组织授予迁移角色。

您可以将迁移角色授予个人用户或团队。我们强烈建议您将迁移角色分配给一个团队。然后，您可以通过调整团队成员资格来进一步定制谁可以运行迁移。有关更改团队成员资格的更多信息，请参阅“将组织成员添加到团队”或“将组织成员从团队中移除”。

要授予迁移角色，请参阅“授予迁移角色”。

授予迁移角色后，确保迁移者使用满足运行迁移所有要求的个人访问令牌。

GitHub 的必需角色

对于 GitHub 上的目标组织，不同的任务需要不同的角色。

下表列出了可以由哪个角色执行哪些任务。

任务组织所有者迁移者
分配迁移角色以进行存储库迁移
运行存储库迁移
下载迁移日志
回收傀儡

个人访问令牌的必需范围

要运行迁移，你需要一个个人访问令牌，该令牌可以访问 GitHub 上的目标组织。

你的 GitHub 个人访问令牌（经典版）所需的范围取决于你的角色和你要完成的任务。

注意：你只能使用个人访问令牌（经典版），而不能使用细粒度个人访问令牌。这意味着，如果你的组织使用“限制个人访问令牌（经典版）访问你的组织”政策，则无法使用 GitHub Enterprise Importer。有关更多信息，请参阅“在你的企业中对个人访问令牌实施政策”。

任务组织所有者迁移者
分配迁移角色以进行存储库迁移admin:org
运行存储库迁移（目标组织）repo、admin:org、workflowrepo、read:org、workflow
下载迁移日志repo、admin:org、workflowrepo、read:org、workflow
回收傀儡admin:org

Bitbucket Server 的必需权限

要从 Bitbucket Server 迁移，你需要

  • 拥有管理员或超级管理员权限的 Bitbucket Server 帐户的用户名和密码
  • 如果你的 Bitbucket Server 实例在 Linux 上运行，则需要 SFTP 访问权限才能访问 Bitbucket Server 实例（请参阅“SSH 密钥”）。一般来说，如果你可以通过 SSH 访问服务器，则也可以使用 SFTP。
  • 如果你的 Bitbucket Server 实例在 Windows 上运行，则需要文件共享 (SMB) 访问权限才能访问 Bitbucket Server 实例

SSH 密钥

如果你的 Bitbucket Server 实例在 Linux 上运行，则必须使用满足以下要求的 SSH 密钥

  • 没有密码短语
  • 使用以下密码之一
    • aes256-ctr
    • 3des-cbc
    • aes128-cbc
    • aes192-cbc
    • aes256-cbc
    • blowfish-cbc
    • twofish-cbc
    • twofish192-cbc
    • twofish128-cbc
    • twofish256-cbc
    • arcfour
    • arcfour128
    • arcfour256
    • cast128-cbc
    • aes128-ctr
    • aes192-ctr

如果你在运行迁移时收到类似于 cipher name aes256-ctr for openssh key file is not supported 的错误，则你的 SSH 私钥使用了不受支持的密码。有关如何生成兼容私钥的更多信息，请参阅“使用 GitHub Enterprise Importer 排除迁移故障”。

授予迁移角色

若要允许除组织所有者之外的人员运行迁移或下载迁移日志，你可以向用户或团队授予迁移角色。有关更多信息，请参阅“关于迁移角色”。

你可以使用 GitHub CLI 的 BBS2GH 扩展或 GraphQL API 授予迁移角色。

使用 BBS2GH 扩展授予迁移角色

若要使用 CLI 授予迁移角色，你必须安装 GitHub CLI 的 BBS2GH 扩展。有关更多信息，请参阅“从 Bitbucket Server 迁移存储库到 GitHub Enterprise Cloud”。

  1. 在 GitHub.com 上，创建并记录一个符合授予迁移角色的所有要求的个人访问令牌。有关更多信息，请参阅“为 GitHub Enterprise Importer 创建个人访问令牌”。

  2. 将个人访问令牌设置为环境变量，用上面记录的个人访问令牌替换以下命令中的 TOKEN。

    • 如果你使用的是终端，请使用 export 命令。

      Shell
      export GH_PAT="TOKEN"

    • 如果你使用的是 PowerShell，请使用 $env 命令。

      Shell
      $env:GH_PAT="TOKEN"

  3. 使用 gh bbs2gh grant-migrator-role 命令，用你想要授予迁移角色的组织替换 ORGANIZATION，用用户或团队名称替换 ACTOR，用 USER 或 TEAM 替换 TYPE。

    Shell
    gh bbs2gh grant-migrator-role --github-org ORGANIZATION --actor ACTOR --actor-type TYPE

使用 GraphQL API 授予迁移角色

您可以使用 grantMigratorRole GraphQL 突变来分配迁移角色，并使用 revokeMigratorRole 突变来撤销迁移角色。

您必须使用满足所有访问要求的个人访问令牌 (PAT)。有关详细信息，请参阅“个人访问令牌的必需范围”。

grantMigratorRole 突变

此 GraphQL 突变设置迁移角色。

mutation grantMigratorRole (
  $organizationId: ID!,
  $actor: String!,
  $actor_type: ActorType!
) {
  grantMigratorRole( input: {
    organizationId: $organizationId,
    actor: $actor,
    actorType: $actor_type
  })
   { success }
}
查询变量说明
organizationId您的组织的 ownerId（或组织 ID），来自 GetOrgInfo 查询。
actor您希望向其分配迁移角色的团队或用户名。
actor_type指定迁移者是 USER 还是 TEAM。

revokeMigratorRole 突变

此突变删除迁移角色。

mutation revokeMigratorRole (
  $organizationId: ID!,
  $actor: String!,
  $actor_type: ActorType!
) {
  revokeMigratorRole( input: {
    organizationId: $organizationId,
    actor: $actor,
    actorType: $actor_type
  })
   { success }
}

为 GitHub Enterprise Importer 创建个人访问令牌

  1. 验证您是否具有完成所需任务的足够角色。有关详细信息，请参阅“必需角色”。
  2. 创建个人访问令牌（经典），确保授予完成所需任务所需的所有范围。您只能使用个人访问令牌（经典），而不能使用细粒度个人访问令牌。有关详细信息，“管理您的个人访问令牌”和“个人访问令牌的必需范围”。
  3. 如果您需要访问的组织强制执行 SAML 单点登录，请授权个人访问令牌进行 SSO。有关详细信息，请参阅“授权个人访问令牌以用于 SAML 单点登录”。

为迁移配置 IP 允许列表

如果您的迁移目标使用 IP 允许列表（GitHub 的 IP 允许列表功能或您的身份提供程序 (IdP) 的 IP 允许列表限制），您需要在 GitHub.com 上配置 IP 允许列表。

  • 如果您使用 GitHub 的 IP 允许列表功能，您必须将以下 GitHub IP 范围添加到目标组织的允许列表中。
  • 如果您使用 IdP 的 IP 允许列表来限制对 GitHub.com 上企业的访问，您应该在迁移完成后禁用企业帐户设置中的这些限制。

有关详细信息，请参阅“管理组织的允许 IP 地址”和“使用 IP 允许列表限制对企业的网络流量”。

识别 GitHub 的 IP 范围

您需要将以下 IP 范围添加到您的 IP 允许列表中

  • 192.30.252.0/22
  • 185.199.108.0/22
  • 140.82.112.0/20
  • 143.55.64.0/20
  • 40.71.233.224/28
  • 2a0a:a440::/29
  • 2606:50c0::/32
  • 20.125.12.8/29 （从 2023 年 11 月 8 日 UTC 00:00 起生效）

您可以随时使用 REST API 的“获取 GitHub 元信息”端点获取 GitHub Enterprise Importer 使用的 IP 范围的最新列表。

响应中的 github_enterprise_importer 键包含用于迁移的 IP 范围列表。

有关更多信息，请参阅“元数据的 REST API 端点”。

延伸阅读