在 GitHub 产品之间迁移时管理访问权限

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

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

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

什么是我的源和目标？

源是您要从中迁移数据的 GitHub.com 或 GitHub Enterprise Server 上的组织。

目标可以是

如果您要迁移仓库，则为 GitHub.com 或 GHE.com 上的**组织**帐户
如果您要迁移整个组织，则为 GitHub.com 或 GHE.com 上的**企业**帐户

我需要哪些访问权限？

要拥有足够的迁移访问权限，对于**源和目标**，您需要以下内容。

组织或企业帐户中的所需角色
可以访问组织或企业帐户的个人访问令牌
- 个人访问令牌必须具有所有所需的作用域，这取决于您的角色和您要完成的任务。
- 如果源或目标对 GitHub.com 使用 SAML 单点登录，则必须为 SSO 授权个人访问令牌。

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

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

关于迁移者角色

为了免除组织所有者完成迁移的需要，GitHub 包含一个用于使用 GitHub Enterprise Importer 的独特角色。

授予迁移者角色允许您指定其他团队或个人来处理您的迁移。

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

警告

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

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

注意

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

必需的角色

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

源组织

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

任务	组织拥有者	迁移者
运行迁移
为存储库迁移分配迁移者角色

目标组织或企业

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

任务	企业拥有者	组织拥有者	迁移者
将组织迁移到企业
为存储库迁移分配迁移者角色
将存储库迁移到组织
下载迁移日志
回收虚拟人

个人访问令牌所需的范围

要运行迁移，您需要一个可以访问目标组织（对于存储库迁移）或企业帐户（对于组织迁移）的个人访问令牌。您还需要另一个可以访问源组织的个人访问令牌。

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

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

注意

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

任务	企业拥有者	组织拥有者	迁移者
为存储库迁移分配迁移者角色		`admin:org`
运行存储库迁移（目标组织）		`repo`、`admin:org`、`workflow`	`repo`、`read:org`、`workflow`
下载迁移日志		`repo`、`admin:org`、`workflow`	`repo`、`read:org`、`workflow`
回收虚拟人		`admin:org`
运行迁移（源组织）		`admin:org`、`repo`	`admin:org`、`repo`
运行组织迁移（目标企业）	`read:enterprise`、`admin:org`、`repo`、`workflow`

授予迁移者角色

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

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

“使用 GEI 扩展授予迁移者角色”
“使用 GraphQL API 授予迁移者角色”

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

要使用 CLI 授予迁移者角色，您必须已安装 GitHub CLI 的 GEI 扩展。有关更多信息，请参阅“将存储库从 GitHub.com 迁移到 GitHub Enterprise Cloud”。

在 GitHub.com 上，创建并记录一个满足授予迁移者角色的所有要求的个人访问令牌。有关更多信息，请参阅“为 GitHub Enterprise Importer 创建个人访问令牌”。
将个人访问令牌设置为环境变量，在以下命令中将 TOKEN 替换为您上面记录的个人访问令牌。
- 如果您使用的是终端，请使用 export 命令。
  Shell
```
export GH_PAT="TOKEN"
```
```
export GH_PAT="TOKEN"
```
- 如果您使用的是 PowerShell，请使用 $env 命令。
  Shell
```
$env:GH_PAT="TOKEN"
```
```
$env:GH_PAT="TOKEN"
```
使用 gh gei grant-migrator-role 命令，将 ORGANIZATION 替换为您要为其授予迁移者角色的组织，将 ACTOR 替换为用户或团队名称，并将 TYPE 替换为 USER 或 TEAM。
Shell
```
gh gei grant-migrator-role --github-org ORGANIZATION --actor ACTOR --actor-type TYPE
```
```
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`	您组织的 `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 创建个人访问令牌

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

为迁移配置 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 存储提供程序的设置，您可能需要更新 Blob 存储提供程序的配置以允许访问以下 GitHub IP 范围。

GitHub.com 的 IP 范围

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

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 日 00:00 UTC 起生效)

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

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

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

GHE.com 的 IP 范围

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

192.30.252.0/22
185.199.108.0/22
140.82.112.0/20
143.55.64.0/20
2a0a:a440::/29
2606:50c0::/32
4.231.155.80/29
4.225.9.96/29
51.12.144.32/29
20.199.1.232/29
51.12.152.184/29
20.199.6.80/29
51.12.152.240/29
20.19.101.136/29
51.12.252.16/28
74.241.131.48/28
20.240.211.176/28
108.143.221.96/28
20.61.46.32/28
20.224.62.160/28

此外，如果您是从 GitHub Enterprise Server 迁移并且使用具有防火墙规则的 Blob 存储帐户

您必须允许访问 GHE.com 的出站 IP 范围。请参阅“GHE.com 的网络详细信息”。
如果您使用的是 Azure Blob 存储，则可能需要执行一些其他配置。请联系 GitHub 支持。

进一步阅读

“组织中的角色”

本文内容