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

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

本文内容

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

为了保护您的数据，GitHub 对使用 GitHub Enterprise Importer 设置了特定的访问要求。这些要求会根据您要执行的任务而有所不同。为避免错误，请仔细阅读本文并确认您已满足所需任务的全部要求。

要将仓库从 Bitbucket Server 迁移到 GitHub，您需要同时拥有源（您的 Bitbucket Server 实例）和目标（GitHub 上的组织）的足够访问权限。要具备足够的访问权限，您需要满足以下全部条件。

  • 目标组织（GitHub）中的必需角色
  • 能够访问目标组织（GitHub）的个人访问令牌
    • 个人访问令牌必须拥有所有必需的作用域，作用域取决于您的角色以及要完成的任务。
    • 如果目标组织在 GitHub 上使用 SAML 单点登录（SSO），则必须为个人访问令牌授权 SSO。
  • Bitbucket Server 所需的权限以及 SFTP 或 SMB 访问

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

关于迁移者角色

为了免除组织所有者亲自完成迁移的需求，GitHub 为使用 GitHub Enterprise Importer 单独提供了一个角色。

授予迁移者角色后，您可以指派其他团队或个人来处理迁移工作。

  • 迁移者角色只能在 GitHub.com 或 GHE.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 访问（请参阅SSH 密钥）。一般而言，只要能够通过 SSH 访问服务器，就可以使用 SFTP。
  • 如果您的 Bitbucket Server 实例运行在 Windows 上，需要对该实例的文件共享（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

如果在迁移时收到类似 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 上创建并记录一个满足授予迁移者角色所有要求的个人访问令牌。更多信息请参阅为 GitHub Enterprise Importer 创建个人访问令牌。

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

    • 如果您使用 Terminal，请使用 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

    注意

    如果您在 GHE.com 为组织授予迁移者角色，还必须包含企业子域的目标 API URL。例如：--target-api-url https://api.octocorp.ghe.com。

通过 GraphQL API 授予迁移者角色

您可以使用 grantMigratorRole GraphQL mutation 来分配迁移者角色，使用 revokeMigratorRole mutation 来撤销该角色。

必须使用满足所有访问要求的个人访问令牌（PAT）。更多信息请参阅个人访问令牌所需的作用域。

grantMigratorRole mutation

此 GraphQL mutation 用于设置迁移角色。

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

revokeMigratorRole mutation

此 mutation 用于移除迁移者角色。

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。更多信息请参阅为单点登录授权个人访问令牌。

为迁移配置 IP 允许列表

如果迁移的目标使用 IP 允许列表（GitHub 的 IP 允许列表功能或您的身份提供商（IdP）的 IP 允许列表限制），则需要在 GitHub 上配置相应的 IP 允许列表。

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

更多信息请参阅管理组织的允许 IP 地址以及使用 IP 允许列表限制企业网络流量。

GitHub.com 的 IP 范围

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

  • 192.30.252.0/22
  • 185.199.108.0/22
  • 140.82.112.0/20
  • 143.55.64.0/20
  • 135.234.59.224/28（已添加于2025年7月28日）
  • 2a0a:a440::/29
  • 2606:50c0::/32
  • 20.99.172.64/28（已添加于2025年7月28日）

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

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

更多信息请参阅REST API 元数据端点。

GitHub.com 的 Azure Blob Storage 虚拟网络防火墙规则

使用 Azure Blob Storage 存储迁移仓库数据的客户必须向其存储帐户添加虚拟网络防火墙规则，以允许 GEI 访问仓库数据。这需要使用 Azure CLI 或 PowerShell，因为在 Azure 门户上添加这些虚拟网络防火墙规则目前不受支持。以下虚拟网络子网 ID 必须添加到存储帐户的虚拟网络防火墙规则中：

  • /subscriptions/cdf1c65c-e6f4-43b3-945f-c5280f104f9c/resourceGroups/ghr-network-service-1a72ec6f-45b6-44be-a4bd-f0fe50079c9f-5-westus2/providers/Microsoft.Network/virtualNetworks/1a72ec6f-45b6-44be-a4bd-f0fe50079c9f-5/subnets/1a72ec6f-45b6-44be-a4bd-f0fe50079c9f-5
  • /subscriptions/173ad082-b20d-4d44-8257-7fbf34959bed/resourceGroups/ghr-network-service-1a72ec6f-45b6-44be-a4bd-f0fe50079c9f-5-westus3/providers/Microsoft.Network/virtualNetworks/1a72ec6f-45b6-44be-a4bd-f0fe50079c9f-5/subnets/1a72ec6f-45b6-44be-a4bd-f0fe50079c9f-5

要将虚拟网络防火墙规则添加到 Azure 存储帐户，请按照为 Azure Storage 创建虚拟网络规则文档的第 5 步进行操作，使用上述网络子网 ID。请务必使用 --subscription 参数并提供与存储帐户关联的订阅 ID。

GHE.com 的 IP 范围

您必须允许以下范围

  • 所有用户均需的范围
  • 根据您数据驻留地区而定的附加范围

有关需添加的范围，请参阅GHE.com 网络详情。

此外，如果您使用带有防火墙规则的 Blob 存储帐户

  • 您必须允许对 GHE.com 的出站 IP 范围的访问。请参阅GHE.com 网络详情。
  • 如果您使用 Azure Blob Storage，可能需要执行一些额外的网络配置。这种情况通常发生在您的 Azure Blob Storage 与 GitHub Enterprise Importer 服务计算所在区域相同的情况下。请联系GitHub 支持获取帮助。

延伸阅读

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