Gerenciando o acesso para uma migração entre produtos GitHub

Sobre o acesso obrigatório para GitHub Enterprise Importer

Para proteger seus dados, o GitHub impõe requisitos de acesso específicos para o uso do GitHub Enterprise Importer. Esses requisitos variam de acordo com a tarefa que você está tentando executar. Para evitar erros, leia este artigo com atenção e verifique se você atende a todos os requisitos da tarefa que deseja concluir.

Para executar uma migração, você precisa ter acesso suficiente à origem e ao destino da migração.

Qual é a origem e o destino?

A origem é a organização em GitHub.com ou GitHub Enterprise Server da qual você deseja migrar dados.

O destino pode ser:

• Uma conta da organização em GitHub.com ou GHE.com, se você estiver migrando repositórios
• Uma conta empresarial no GitHub.com ou no GHE.com, caso você esteja migrando uma organização inteira

De qual acesso eu preciso?

Para ter acesso suficiente à origem e ao destino da migração, você precisa dos itens a seguir.

• Uma função necessária na conta da organização ou empresa
• Um personal access token que pode acessar a organização ou a conta corporativa
  • O personal access token deve ter todos os escopos necessários, que dependem do seu perfil e da tarefa que você deseja realizar.
  • Se a origem ou o destino usar logon único com SAML para GitHub.com, você deverá autorizar o personal access token para SSO.

Além disso, se você usar listas de permissões de IP com a origem ou o destino, talvez seja necessário configurar as listas de permissões para permitir o acesso por GitHub Enterprise Importer.

Se você estiver migrando da GitHub Enterprise Server versão 3.8 ou superior pela primeira vez, também precisará de alguém que tenha acesso a Console de Gerenciamento para configurar o armazenamento de blobs para sua instância do GitHub Enterprise Server.

Sobre a função de migrador

Para remover a necessidade de os proprietários da organização concluírem as migrações, o GitHub inclui uma função distinta para usar o GitHub Enterprise Importer.

A concessão da função de migrador permite designar outras equipes ou pessoas para lidar com as migrações.

• Você só pode conceder a função de migrador para uma organização no GitHub.com ou no GHE.com.
• Você pode conceder a função de migrador a um usuário individual ou a uma equipe. Recomendamos fortemente que você atribua a função de migrador a uma equipe. Em seguida, você poderá personalizar ainda mais quem pode executar uma migração ajustando a associação à equipe. Confira Adicionar integrantes da organização a uma equipe ou Remover integrantes da organização de uma equipe.
• O migrador precisa usar um personal access token que atenda a todos os requisitos para executar migrações.

Para conceder a função de migrador, confira Como conceder a função de migrador.

Funções necessárias

Para a origem e o destino da migração, são necessárias funções diferentes para tarefas diferentes.

Organização de origem

A tabela a seguir lista quais funções podem executar quais tarefas.

Tarefa	Proprietário da organização	Migrador
Executar uma migração
Como atribuir a função de migrador para migrações de repositório

Organização ou empresa de destino

A tabela a seguir lista quais funções podem executar quais tarefas.

Tarefa	Proprietário corporativo	Proprietário da organização	Migrador
Migrando organizações para uma empresa
Como atribuir a função de migrador para migrações de repositório
Migrando repositórios para uma organização
Como baixar um log de migração
Como recuperar manequins

Escopos obrigatórios para personal access tokens

Para executar uma migração, você precisa de um personal access token que possa acessar a organização de destino (para migrações de repositório) ou a conta corporativa (para migrações da organização). Você também precisa de outro personal access token que possa acessar a organização de origem.

Para outras tarefas, como baixar um log de migração, você só precisa de uma personal access token que possa acessar o destino da operação.

Os escopos necessários para sua GitHubpersonal access token (classic) função dependem da função e da tarefa que você deseja concluir.

Tarefa	Proprietário corporativo	Proprietário da organização	Migrador
Como atribuir a função de migrador para migrações de repositório		admin:org
Como executar uma migração de repositório (organização de destino)
repo
admin:org
workflow
repo
read:org
workflow

Como baixar um log de migração | | repo admin:org workflow | repo read:org workflow

Como recuperar manequins | | admin:org | Como executar uma migração (organização de origem) | | admin:org, repo | admin:org, repo | Como executar uma migração de organização (empresa de destino) | read:enterprise, admin:org, , repo``workflow | | |

Concedendo o papel de migrador

Para permitir que alguém que não seja um proprietário da organização execute uma migração de repositório ou faça download de logs de migração, você pode conceder a função de migrador a um usuário ou equipe. Para mais informações, consulte Sobre a função de migrador.

Você pode conceder a função de migrador usando GEI extension of the GitHub CLI ou a API GraphQL.

• Concedendo a função de migrador com o GEI extension
• Como conceder a função de migrador com a API do GraphQL

Concedendo a função de migrador com o GEI extension

Para conceder a função de migrador usando a CLI, você deve ter instalado o GEI extension of the GitHub CLI. Para saber mais, confira Como migrar repositórios do GitHub.com para o GitHub Enterprise Cloud.

1. Em GitHub.com, crie e registre um(a) personal access token que atenda a todos os requisitos para a concessão da função de migrador. Para obter mais informações, consulte Criando um personal access token para GitHub Enterprise Importer.

2. Defina o personal access token como uma variável de ambiente, substituindo TOKEN nos comandos abaixo pelos personal access token que você registrou acima.

   • Se você estiver usando o Terminal, use o comando export.

     Shell

     export GH_PAT="TOKEN"
     

   • Se você estiver usando o PowerShell, use o comando $env.

     Shell

     $env:GH_PAT="TOKEN"
     

3. Use o comando gh gei grant-migrator-role, substituindo ORGANIZATION pela organização à qual você deseja conceder a função de migrador, ACTOR pelo nome do usuário ou da equipe e TYPE por USER ou TEAM.

   Shell

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

   Observação

   Se você estiver concedendo a função de migrador para o GHE.com, também precisará incluir a URL de API de destino para o subdomínio da sua empresa. Por exemplo: --target-api-url https://api.octocorp.ghe.com.

Como conceder a função de migrador com a API do GraphQL

Use a mutação grantMigratorRole do GraphQL para atribuir a função de migrador e a mutação revokeMigratorRole para revogar a função de migrador.

Você precisa usar um PAT (personal access token) que atenda a todos os requisitos de acesso. Para obter mais informações, confira Escopos necessários para os personal access tokens.

Mutação grantMigratorRole

Essa mutação do GraphQL define a função de migração.

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

Variável da consulta	Descrição
organizationId	A ownerId (ou ID da organização) para sua organização, da consulta GetOrgInfo.
actor	O nome da equipe ou do usuário ao qual você deseja atribuir a função de migração.
actor_type	Especifique se o migrador é um USER ou uma TEAM.

Mutação revokeMigratorRole

Essa mutação remove a função de migrador.

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

Criando um personal access token para GitHub Enterprise Importer

1. Verifique se você tem uma função suficiente para a tarefa que deseja concluir. Para obter mais informações, confira Funções necessárias.
2. Crie um personal access token (classic), certificando-se de conceder todos os escopos necessários para a tarefa que você deseja concluir. Você só pode usar um personal access token (classic), não um fine-grained personal access token. Para obter mais informações, Gerenciar seus tokens de acesso pessoal e escopos necessários para personal access token.
3. Se o logon único via SAML for exigido para as organizações que você precisa acessar, autorize o personal access token para SSO. Para saber mais, confira Como autorizar um token de acesso pessoal para uso com logon único.

Como configurar listas de permissões de IP para migrações

Se a origem ou o destino da sua migração usa uma lista de permissões de IP, o recurso de lista de permissões de IP (do GitHub ou as restrições de lista de permissões de IP do IdP [provedor de identidade], como o CAP do Azure), você precisa configurar listas de permissões de IP no GitHub. Confira Gerenciar endereços IP permitidos para sua organização e Como restringir o tráfego de rede para sua empresa com uma lista de permissões de IP.

• Se você usar o recurso de lista de permissões de IP do GitHub, precisará adicionar os intervalos de IP do GitHub abaixo à lista de permissões para as organizações de origem e/ou de destino.
• Se você usar a lista de permissões de IP do IdP para restringir o acesso à sua empresa no GitHub, desabilite essas restrições nas configurações da conta corporativa até que a migração seja concluída.

Os intervalos de IP podem variar, dependendo se o destino da migração é o GitHub.com ou o GHE.com.

Se a origem da sua migração for GitHub Enterprise Server, você não precisará adicionar nenhum intervalo de IP de GitHub à configuração do firewall nem à lista de permissão de IP em sua instância do GitHub Enterprise Server. No entanto, dependendo da configuração do seu provedor de armazenamento de blobs, talvez seja necessário atualizar a configuração do provedor de armazenamento de blobs para permitir o GitHub acesso aos intervalos de IP abaixo.

Intervalos de IP para GitHub.com

Você precisará adicionar os seguintes intervalos de IP às listas de IPs permitidos:

• 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 (adicionado em 28 de julho de 2025)
• 2a0a:a440::/29
• 2606:50c0::/32
• 20.99.172.64/28 (adicionado em 28 de julho de 2025)

Você pode obter uma lista atualizada dos intervalos de IP usados em GitHub Enterprise Importer a qualquer momento com o endpoint "Obter GitHub informações meta" da API REST.

A chave github_enterprise_importer na resposta contém uma lista de intervalos de IP usados para as migrações.

Para saber mais, confira Pontos de extremidade da API REST para metadados.

Regras de firewall para rede virtual do Armazenamento de Blobs do Azure para GitHub.com

Clientes com o Armazenamento de Blobs do Azure configurado para armazenar dados do repositório para migrações devem adicionar regras de firewall de rede virtual às contas de armazenamento para permitir que o GEI acesse os dados do repositório. Isso requer o uso da CLI do Azure ou do PowerShell, pois a adição dessas regras de firewall de rede virtual no Portal do Azure não tem suporte no momento. As seguintes IDs de sub-rede de rede virtual devem ser adicionadas às regras de firewall da rede virtual para sua conta de armazenamento:

• /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

Para adicionar as regras de firewall de rede virtual à sua conta de Armazenamento do Azure, você pode seguir a etapa 5 na documentação para criar uma regra de rede virtual para o Armazenamento do Azure usando as IDs de sub-rede de rede fornecidas acima. Certifique-se de fornecer o argumento --subscription com a ID de assinatura vinculada à conta de armazenamento.

Intervalos de IP para GHE.com

Você pode obter uma lista atualizada dos intervalos de IP usados em GitHub Enterprise Importer a qualquer momento com o endpoint "Obter GitHub informações meta" da API REST.

A chave github_enterprise_importer na resposta contém uma lista de intervalos de IP usados para as migrações.

Além disso, se você estiver migrando de GitHub Enterprise Server e usando uma conta de armazenamento de blobs com regras de firewall:

• Você precisa permitir o acesso aos intervalos de IP de saída para o GHE.com. Confira Detalhes de rede do GHE.com.
• Caso você esteja usando o Armazenamento de Blobs do Azure, talvez seja necessário fazer uma configuração de rede adicional. Isso poderá ocorrer se o Armazenamento de Blobs do Azure estiver localizado na mesma região que a computação do serviço GitHub Enterprise Importer. Entre em contato com o Suporte do GitHub.

Leitura adicional

• Funções em uma organização