管理 GitHub 产品迁移的访问权限

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

本文内容

关于GitHub 企业导入器所需的访问权限

为保护您的数据，GitHub 对使用 GitHub 企业导入器设定了特定的访问要求。这些要求会根据您要执行的任务而有所不同。为避免错误，请仔细阅读本文并确认您已满足要完成的任务的所有要求。

要运行迁移，您需要对迁移的源和目标都拥有足够的访问权限。

我的来源和目标是什么？

来源是指您想要迁移数据的 GitHub.com 或 GitHub Enterprise Server 上的组织。

目标可以是

  • 在 GitHub.com 或 GHE.com 上的组织账户（如果您正在迁移仓库）
  • 在 GitHub.com 或 GHE.com 上的企业账户（如果您正在迁移整个组织）

我需要什么访问权限？

要对迁移拥有足够的访问权限，源和目标都必须满足以下要求。

  • 组织或企业账户中的必需角色
  • 能够访问组织或企业账户的个人访问令牌
    • 个人访问令牌必须具备所有必需的范围，范围取决于您的角色以及您想要完成的任务。
    • 如果源或目标在 GitHub.com 上使用 SAML 单点登录，您必须为该个人访问令牌授权 SSO。

此外，如果您在源或目标上使用 IP 允许列表，可能需要配置该列表以允许 GitHub 企业导入器访问。

如果您首次从 GitHub Enterprise Server 3.8 或更高版本迁移，还需要有权访问管理控制台的人员为您的 GitHub Enterprise Server 实例设置 Blob 存储。

关于迁移者角色

为去除组织所有者必须完成迁移的需求，GitHub 为使用 GitHub 企业导入器提供了独立的迁移者角色。

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

  • 您只能在 GitHub.com 或 GHE.com 上的组织中授予迁移者角色。
  • 您可以将迁移者角色授予单个用户或团队。我们强烈建议将迁移者角色分配给团队。这样，您可以通过调整团队成员进一步自定义谁可以运行迁移。参见 将组织成员添加到团队 或 从团队中移除组织成员。
  • 迁移者必须使用满足运行迁移所有要求的个人访问令牌。

警告

当您在组织中将迁移者角色授予用户或团队时，即赋予他们在该组织内导入或导出任何仓库的权限。

若要授予迁移者角色，请参见 授予迁移者角色。

注意

  • 如果您在两个组织之间迁移仓库，可以为同一人或团队在两个组织中分别授予迁移者角色，但必须分别进行授予。
  • 您无法为企业账户授予迁移者角色。因此，只有当您是目标企业的所有者时才能运行组织迁移。不过，您可以为源组织的企业所有者授予迁移者角色。
  • GitHub CLI 不支持为 GitHub Enterprise Server 上的组织授予迁移者角色，因此您必须是源组织的所有者才能从 GitHub Enterprise Server 迁移仓库。

必需的角色

针对迁移的源和目标，不同任务需要不同的角色。

源组织

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

任务组织所有者迁移者
执行迁移
为仓库迁移分配迁移者角色

目标组织或企业

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

任务企业所有者组织所有者迁移者
将组织迁移到企业
为仓库迁移分配迁移者角色
将仓库迁移到组织
下载迁移日志
回收假人

个人访问令牌所需的范围

要运行迁移，您需要一个能够访问目标组织（用于仓库迁移）或企业账户（用于组织迁移）的个人访问令牌。您还需要另一个能够访问源组织的个人访问令牌。

对于其他任务（例如下载迁移日志），只需要一个能够访问操作目标的个人访问令牌。

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

注意

您只能使用个人访问令牌（经典），而不能使用细粒度个人访问令牌。这意味着如果您的组织使用“限制个人访问令牌（经典）访问您的组织”策略，则无法使用 GitHub Enterprise Importer。更多信息，请参见 在企业中强制执行个人访问令牌的策略。

任务企业所有者组织所有者迁移者
为仓库迁移分配迁移者角色admin:org
执行仓库迁移（目标组织）repo, admin:org, workflowrepo, read:org, workflow
下载迁移日志repo, admin:org, workflowrepo, read:org, workflow
回收假人admin:org
执行迁移（源组织）admin:org, repoadmin:org, repo
执行组织迁移（目标企业）read:enterprise, admin:org, repo, workflow

授予迁移者角色

若要让组织所有者之外的其他人运行仓库迁移或下载迁移日志，您可以将迁移者角色授予用户或团队。详情请参见 关于迁移者角色。

您可以使用 GitHub CLI 的 GEI 扩展或 GraphQL API 授予迁移者角色。

使用 GEI 扩展授予迁移者角色

要通过 CLI 授予迁移者角色，必须已安装 GitHub CLI 的 GEI 扩展。更多信息请参阅 从 GitHub.com 迁移仓库到 GitHub Enterprise Cloud。

  1. 在 GitHub.com 上创建并记录一个满足授予迁移者角色所有要求的个人访问令牌。更多信息请参见 为 GitHub 企业导入器创建个人访问令牌。

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

    • 如果您使用 Terminal，请使用 export 命令。

      Shell
      export GH_PAT="TOKEN"

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

      Shell
      $env:GH_PAT="TOKEN"

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

    Shell
    gh gei 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 突变来分配迁移者角色，使用 revokeMigratorRole 突变来撤销迁移者角色。

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

grantMigratorRole 突变

此 GraphQL 突变用于设置迁移角色。

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 revokeMigratorRole (
  $organizationId: ID!,
  $actor: String!,
  $actor_type: ActorType!
) {
  revokeMigratorRole( input: {
    organizationId: $organizationId,
    actor: $actor,
    actorType: $actor_type
  })
   { success }
}

为 GitHub 企业导入器创建个人访问令牌

  1. 请确认您已拥有完成该任务所需的足够角色。更多信息请参见 必需的角色。
  2. 创建一个个人访问令牌（经典），确保授予任务所需的所有范围。只能使用个人访问令牌（经典），不能使用细粒度个人访问令牌。更多信息请参阅 管理您的个人访问令牌 和 个人访问令牌所需的范围。
  3. 如果组织强制使用 SAML 单点登录，请为个人访问令牌授权 SSO。更多信息请参见 授权个人访问令牌以用于单点登录。

为迁移配置 IP 允许列表

如果迁移的源或目标使用 IP 允许列表（GitHub 的 IP 允许列表功能或身份提供商（IdP）的 IP 允许列表限制，例如 Azure CAP），您需要在 GitHub 上配置 IP 允许列表。参见 管理组织的允许 IP 地址 和 使用 IP 允许列表限制对企业的网络流量。

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

IP 范围取决于迁移的目标是 GitHub.com 还是 GHE.com。

如果迁移的源是 GitHub Enterprise Server，您无需将任何 GitHub IP 范围添加到防火墙配置或 GitHub Enterprise Server 实例的 IP 允许列表中。但根据您的 Blob 存储提供商的设置，可能需要更新该提供商的配置以允许访问以下 GitHub 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 企业导入器使用的最新 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 Storage 帐户，可按照 为 Azure Storage 创建虚拟网络规则 文档的第 5 步操作，使用提供的网络子网 ID，并确保在 --subscription 参数中填写对应存储帐户所属的订阅 ID。

GHE.com 的 IP 范围

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

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

另外，如果您从 GitHub Enterprise Server 迁移且使用了带防火墙规则的 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.