Enterprise Server 3.15 目前作为候选发布提供。

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

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

本文内容

关于 GitHub Enterprise Importer

所需的访问权限

为了保护数据，GitHub 强制实施特定的访问要求来使用 GitHub Enterprise Importer。 这些要求会因尝试执行的任务而异。 为防止出错，应仔细查看本文，并确认是否符合要完成的任务的所有要求。

要将存储库从 Bitbucket Server 迁移到 GitHub，需对源（Bitbucket 服务器实例）和目标（GitHub 上的组织）具有足够的访问权限。 要具有足够的访问权限，需满足以下条件：

  • GitHub 上目标组织中的必需角色
  • 可以访问 GitHub 上目标组织的 personal access token
    • personal access token 必须具有所有必需的范围，具体取决于你的角色和要完成的任务。
    • 如果目标组织对 GitHub 使用 SAML 单一登录，则必须授权 personal access token 以实现 SSO。
  • Bitbucket Server 必需的权限以及 SFTP 或 SMB 访问权限

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

关于迁移者角色

为了使组织所有者不再需要完成迁移， GitHub 包含使用 GitHub Enterprise Importer 的不同角色。 通过授予迁移者角色，可以指定其他团队或个人来处理迁移。 只能为 GitHub.com 上的组织授予迁移者角色。

可以将迁移者角色授予单个用户或团队。 强烈建议将迁移者角色分配给团队。 然后，可以通过调整团队成员身份来进一步自定义可运行迁移的人员。 有关更改团队成员身份的详细信息，请参阅“添加组织成员到团队”或“从团队中删除组织成员”。

Warning

将组织中的迁移者角色授予用户或团队时，即授予他们导入或导出该组织中的任何存储库的能力。

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

授予迁移者角色后，请确保迁移者使用的 personal access token 满足运行迁移的所有要求。

GitHub

所需的角色

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

下表列出了可以执行某些任务的具体角色。

任务组织所有者迁移者
为存储库迁移分配迁移者角色
运行存储库迁移
下载迁移日志
回收模型

personal access token 所需的范围

要运行迁移，需要一个可以访问 GitHub 上目标组织的 personal access token。

GitHub personal access token (classic) 所需的范围取决于你的角色和要完成的任务。

注意：只能使用 personal access token (classic)，而不能使用 fine-grained personal access token。这意味着，如果贵组织使用“限制 personal access tokens (classic) 访问组织”策略，则你无法使用 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 上运行，则为对 Bitbucket Server 实例的 SFTP 访问权限（请参阅“SSH 密钥”）。 通常，如果可以通过 SSH 访问该服务器，则也可以使用 SFTP。
  • 如果 Bitbucket Server 实例在 Windows 上运行，则为对 Bitbucket Server 实例的文件共享 (SMB) 访问权限

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

如果运行迁移时收到以下错误，SSH 私钥将使用不受支持的密码：cipher name aes256-ctr for openssh key file is not supported。 若要详细了解如何生成兼容的私钥，请参阅“使用 GitHub Enterprise Importer 排查迁移问题”。

授予迁移者角色

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

可以使用 BBS2GH extension of the GitHub CLI 或 GraphQL API 授予迁移者角色。

使用 BBS2GH extension

授予迁移者角色

若要使用 CLI 授予迁移者角色，必须已安装 BBS2GH extension of the GitHub CLI。 有关详细信息，请参阅“将存储库从 Bitbucket Server 迁移到 GitHub Enterprise Cloud”。

  1. 在 GitHub 上，创建并记录满足授予迁移者角色的所有要求的 personal access token。 有关详细信息，请参阅“为 GitHub Enterprise Importer 创建 personal access token。”

  2. 将 personal access token 设置为环境变量，将以下命令中的 TOKEN 替换为你在上面记录的 personal access token。

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

      Shell
      export GH_PAT="TOKEN"

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

      Shell
      $env:GH_PAT="TOKEN"

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

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

使用 GraphQL API 授予迁移者角色

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

必须使用满足所有访问要求的 personal access token (PAT)。 有关详细信息，请参见“personal access token 所需的作用域。”

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

创建 personal access token

  1. 验证是否有足够的角色权限来完成要完成的任务。 有关详细信息，请参阅“必需的角色”。
  2. 创建 personal access token (classic)，确保授予要完成的任务所需的全部范围。 只能使用 personal access token (classic)，而不能使用 fine-grained personal access token。 有关详细信息，请参阅“管理个人访问令牌”和“personal access token 所需的范围”。
  3. 如果对需要访问的组织强制实施 SAML 单一登录，请授权 personal access token 以实现 SSO。 有关详细信息，请参阅“授权用于 SAML 单点登录的个人访问令牌”。

为迁移配置 IP 允许列表

如果迁移的目标使用 IP 允许列表（GitHub的 IP 允许列表功能或标识提供者的 (IdP) IP 允许列表限制），则需要在 GitHub 上配置 IP 允许列表。

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

有关详细信息，请参阅“管理组织允许的 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 （从 UTC 2023 年 11 月 8 日 00:00 起生效）

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

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

有关详细信息，请参阅“元数据的 REST API 终结点”。

延伸阅读