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

Sobre o acesso necessário do 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. A origem é a organização em GitHub.com ou GitHub Enterprise Server da qual você quer migrar. O destino é uma conta da organização em GitHub.com, se você estiver migrando repositórios, ou uma conta corporativa em GitHub.com, se estiver migrando uma organização inteira.

Para ter acesso suficiente à origem ou ao destino para a migração, você precisa do seguinte:

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

Além disso, caso você use 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 do GitHub Enterprise Importer.

Se você estiver migrando do GitHub Enterprise Server 3.8 ou superior pela primeira vez, você também precisa de alguém com acesso ao 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 a uma organização do GitHub.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. Para obter mais informações sobre como alterar a associação à equipe, confira "Adicionar integrantes da organização a uma equipe" ou "Remover integrantes da organização de uma equipe".

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

Depois de conceder a função de migrador, verifique se o migrador usa um personal access token que atenda a todos os requisitos para executar migrações.

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 necessários para os personal access tokens

Para executar uma migração, você precisa de um personal access token que possa acessar a organização de destino (para as migrações de repositório) ou a conta corporativa (para as 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 um personal access token que possa acessar o destino da operação.

Os escopos necessários para o GitHub personal access token (classic) dependem da sua 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 a função 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 obter mais informações sobre a função de migrador, confira "Sobre a função de migrador".

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

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

Como conceder a função de migrador com a GEI extension

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

1. No GitHub.com, crie e registre um personal access token que atenda a todos os requisitos para conceder a função de migrador. Para obter mais informações, consulte "Como criar 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
   

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, consulte "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 }
}

Como criar um personal access token para o 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), lembrando-se de conceder todos os escopos necessários para a tarefa que 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 o personal access token".
3. Se o logon único do SAML for imposto para as organizações que você precisa acessar, autorize o personal access token para SSO. Para obter mais informações, confira "Autorizar o uso de um token de acesso pessoal para uso com logon único SAML".

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.

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

Para obter mais informações, 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 a origem da migração for o GitHub Enterprise Server, você não precisará adicionar nenhum intervalo de IP do GitHub à configuração do firewall ou à lista de permissões de IP no sua instância do GitHub Enterprise Server. No entanto, dependendo da configuração do provedor de armazenamento de blobs, talvez seja necessário atualizar a configuração do provedor de armazenamento de blobs para permitir o acesso aos intervalos de IP do GitHub abaixo.

Como identificar os intervalos de IP do GitHub

Você precisará adicionar os seguintes intervalos de IP à(s) sua(s) lista(s) de permissões de 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 (ativo a partir das 00h00min UTC de 8 de novembro de 2023)

Você pode obter uma lista atualizada de intervalos de IP usados pelo GitHub Enterprise Importer a qualuqer momento com o ponto de extremidade "Obter metainformações do GitHub da API REST.

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

Para obter mais informações, confira "Pontos de extremidade da API REST para metadados".

Leitura adicional

• "Funções em uma organização"