Visão geral de uma migração entre produtos GitHub

Saiba como concluir todo o processo de migração de um produto do GitHub para outro com o GitHub Enterprise Importer, desde o planejamento até a implementação e a conclusão das tarefas de acompanhamento.

Neste artigo

Visão geral

Com o GitHub Enterprise Importer, você pode migrar para o GitHub Enterprise Cloud. Para obter mais informações, confira "Sobre o GitHub Enterprise Importer".

Se você estiver migrando entre produtos do GitHub, como do GitHub Enterprise Server para o GitHub Enterprise Cloud, use este guia para planejar e implementar a migração e concluir as tarefas de acompanhamento. Para ver a lista completa de caminhos de migração com suporte, confira "Sobre o GitHub Enterprise Importer".

Como planejar a migração

Para planejar sua migração, faça as perguntas a seguir.

Desejamos migrar por organização ou por repositório?

Primeiro, se a origem e o destino da migração forem o GitHub.com, decida se deseja fazer a migração por organização ou por repositório.

Observação: se você estiver migrando do GitHub Enterprise Server, só poderá migrar repositórios.

Se você escolher as migrações por repositório, somente os dados no nível do repositório serão migrados. Se você escolher a estratégia de migração por organização, os dados selecionados no nível da organização também serão migrados, incluindo as equipes e o acesso delas aos repositórios.

No entanto, quando você migra uma organização, todos os repositórios pertencentes à organização de origem são migrados ao mesmo tempo. Não é possível dividir os repositórios em lotes ou ignorar a migração de um dos repositórios da organização. Caso você tenha um grande número de repositórios ou caso não possa tolerar o tempo de inatividade de todos os repositórios ao mesmo tempo, talvez seja necessário executar migrações de repositório.

Além disso, uma migração da organização cria uma organização na conta corporativa de destino. Se você desejar migrar repositórios para uma organização existente, precisará executar migrações de repositório.

Por fim, você precisa ser um proprietário corporativo da conta corporativa de destino para migrar organizações. Se quiser encarregar alguém que não seja um proprietário corporativo a executar as migrações, ele precisará executar migrações de repositório.

Em quanto tempo precisamos concluir a migração?

Determine a linha do tempo, que determinará, principalmente, sua abordagem. A primeira etapa para determinar a linha do tempo é obter um inventário do que você precisa migrar. Para coletar esses dados, use a extensão gh-repo-stats para o GitHub CLI. Essa ferramenta de código aberto gera um relatório que fornece detalhes do volume de dados existente para migração de uma organização.

Observação: gh-repo-stats é uma ferramenta de código aberto que não tem suporte do Suporte do GitHub. Se você precisar de ajuda com essa ferramenta, abra um problema no repositório dela.

  • Número de repositórios
  • Número de solicitações de pull
  • Número de problemas
  • Número de usuários
  • Uso de projetos e wikis

O tempo de migração baseia-se, em grande parte, no número de solicitações de pull e problemas de um repositório. Se você desejar migrar mil repositórios e cada repositório tiver, em média, 100 solicitações de pull e problemas e apenas 50 usuários tiverem contribuído para os repositórios, provavelmente, sua migração será muito rápida. Se você desejar migrar apenas 100 repositórios, mas cada um dos repositórios tiver 75 mil solicitações de pull e problemas e cinco mil usuários, a migração levará mais tempo e exigirá muito mais planejamento e teste.

Depois de usar o analisador, você pode analisar seus dados de inventário em relação à linha do tempo desejada. Se a sua organização puder suportar um grau mais alto de alteração, você poderá migrar todos os repositórios de uma só vez, concluindo os esforços de migração em alguns dias. No entanto, talvez você tenha várias equipes que não possam migrar ao mesmo tempo. Nesse caso, o ideal será fazer as migrações em lote e escaloná-las para ajustá-las às linhas do tempo das equipes, estendendo o esforço de migração.

  1. Use a extensãogh-repo-stats para a GitHub CLI e revise seu inventário de migração.
  2. Para entender quando as equipes podem estar prontas para a migração, entreviste os stakeholders.
  3. Leia na íntegra o restante deste guia e tome uma decisão sobre uma linha do tempo de migração.

Observação: gh-repo-stats é uma ferramenta de código aberto que não tem suporte do Suporte do GitHub. Se você precisar de ajuda com essa ferramenta, abra um problema no repositório dela.

Entendemos o que será migrado?

Verifique se você e seus stakeholders entendem quais dados podem ser migrados pelo GitHub Enterprise Importer.

  1. Revise os dados migrados para a origem de migração. Para obter mais informações, confira "Sobre migrações entre produtos GitHub".
  2. Faça uma lista de todos os dados que você precisará migrar ou recriar manualmente.

Quem executará a migração?

Decida quem executará as migrações e verifique se essa pessoa tem o acesso necessário. Suas opções dependerão se você estiver fazendo a migração por organização ou por repositório.

Como decidir quem executará as migrações de organização

Para migrar uma organização, você precisa ser um proprietário da organização na organização de origem, ou um proprietário da organização precisa conceder a você a função de migrador nessa organização.

Além disso, você precisa ser um proprietário corporativo na conta corporativa de destino. Não é possível conceder a função de migrador a contas corporativas.

  1. Confirme se a pessoa que executará as migrações é um proprietário corporativo da conta corporativa de destino.
  2. Se essa pessoa não for um proprietário da organização de origem, conceda a ela a função de migrador na organização. Para obter mais informações, confira "Gerenciando o acesso para uma migração entre produtos GitHub".
  3. Confirme se a pessoa configurou os personal access tokens corretamente para atender a todos os requisitos de acesso. Para obter mais informações, confira "Gerenciando o acesso para uma migração entre produtos GitHub."

Como decidir quem executará as migrações de repositório

Para migrar um repositório, você precisa ser um proprietário da organização na organização de origem e na organização de destino, ou um proprietário da organização precisa conceder a você a função de migrador para cada organização na qual você não seja o proprietário.

  1. Decida se deseja que um proprietário da organização de destino execute as migrações ou se precisa conceder a função de migrador a outra pessoa.

  2. Se você optar por conceder a função de migrador, decida a qual pessoa ou equipe você concederá a função.

  3. Conceda a função de migrador à pessoa ou à equipe. Para obter mais informações, confira "Gerenciando o acesso para uma migração entre produtos GitHub".

    Observação: lembre-se de conceder a função de migrador à organização de origem e à organização de destino.

  4. Confirme se a pessoa configurou os personal access tokens corretamente para atender a todos os requisitos de acesso. Para obter mais informações, confira "Gerenciando o acesso para uma migração entre produtos GitHub."

Desejamos manter uma estrutura de organização semelhante após a migração?

Em seguida, considere se você deseja manter uma estrutura organizacional semelhante após a migração. Se você desejar dividir seu esforço de migração em lotes, isso ajudará você a determinar os lotes. Se você pretende manter uma correspondência um-para-um entre as organizações na origem e no destino, recomendamos as migrações em lote por organização. Essa é a abordagem mais simples, especialmente se você estiver migrando do GitHub.com, pois você pode migrar uma organização inteira com um só comando. Se você estiver migrando de outra fonte, o GitHub CLI poderá gerar um script para migrar todos os repositórios em uma só organização.

Se você pretende alterar a estrutura organizacional, considere outros fatores de envio em lote. Você pode enviar em lote os repositórios pertencentes a equipes semelhantes ou a uma divisão de negócios ou fazer o envio em lote pela organização de destino. Recomendamos o envio em lote por equipes, se possível. Se você usar a migração em lote por organizações de destino ou divisão de negócios, aumentará o número de stakeholders envolvidos, o que pode resultar em janelas de tempo mais curtas para as migrações.

Mesmo que você altere a estrutura organizacional, ainda poderá preparar um script para a migração. Use o comando da GitHub CLI e mova as linhas de cada repositório para scripts diferentes, conforme necessário.

Observação: você pode executar vários lotes simultaneamente. Por exemplo, se você estiver fazendo um envio em lote por equipes, poderá executar as migrações para várias equipes na mesma janela de tempo.

  1. Decida qual será a estrutura da sua nova organização.
  2. Decida se você precisa dividir seu esforço de migração em lotes menores.
  3. Nesse caso, decida como deseja interromper as migrações.

Como executar as migrações

Depois de concluir o planejamento, você poderá iniciar as migrações reais. Para ajudar a descobrir problemas que podem ser exclusivos da sua empresa durante e após a migração, recomendamos fortemente fazer execuções de avaliação de todas as migrações. Depois de resolver os problemas descobertos pelas execuções de avaliação, você poderá executar as migrações de produção.

As migrações de avaliação ajudam você a determinar várias informações críticas.

  • Indica se a migração para determinado repositório pode ser concluída com sucesso
  • Indica se você pode restaurar o repositório para um estado em que os usuários podem começar a trabalhar
  • O tempo que uma migração levará para ser executada, o que é útil para planejar agendamentos de migração e definir as expectativas dos stakeholders

As execuções de avaliação não exigem muita coordenação de tempo. O GitHub Enterprise Importer nunca exige tempo de inatividade para os usuários de um repositório que está sendo migrado. No entanto, recomendamos interromper o trabalho durante as migrações de produção para garantir que não sejam criados dados durante a migração, que não estarão no repositório migrado. Essa não é uma preocupação para as migrações de avaliação, ou seja, as execuções de avaliação podem ocorrer a qualquer momento. Para reduzir o tempo necessário para concluir as migrações de avaliação, você pode agendar os lotes para as execuções de avaliação sucessivas. Os usuários desses repositórios podem validar os resultados em um tempo próprio.

Para as migrações de repositório, recomendamos criar uma organização de teste para usá-la como destino para as migrações de avaliação. Use uma organização individual para todas as execuções de avaliação ou crie uma organização de teste para cada organização de destino pretendida. Considere a inclusão de -sandbox no final dos nomes da organização, para esclarecer que as organizações se destinam apenas à validação de migração e não à produção. Você pode excluir as organizações de teste depois de terminar.

  1. Se você estiver executando uma migração de repositório, crie uma organização de teste para as migrações de avaliação.
  2. Se a organização de origem usar listas de IPs permitidos, configure a lista para permitir o acesso do GitHub Enterprise Importer. Para obter mais informações, confira "Gerenciando o acesso para uma migração entre produtos GitHub".
  3. Execute as migrações de avaliação.
  4. Conclua as tarefas de acompanhamento descritas abaixo para as migrações de avaliação.
  5. Solicite aos usuários que validem os resultados das migrações.
  6. Resolva os problemas descobertos pelas migrações de avaliação.
  7. Se o destino usar listas de IPs permitidos, configure a lista para permitir o acesso do GitHub Enterprise Importer. Para obter mais informações, confira "Gerenciando o acesso para uma migração entre produtos GitHub."
  8. Se você estiver executando uma migração de repositório e quiser migrar as configurações do GitHub Advanced Security, habilite o GitHub Advanced Security para a organização de destino. Para obter mais informações, confira "Gerenciando as configurações de segurança e de análise da sua organização".
  9. Execute as migrações de produção. Para obter mais informações, confira "Sobre o GitHub Enterprise Importer" ou "Como migrar organizações do GitHub.com para o GitHub Enterprise Cloud".
  10. Opcionalmente, exclua a organização de teste.

Como concluir as tarefas de acompanhamento

Após a conclusão de cada migração, você precisará realizar algumas tarefas adicionais antes que o repositório fique pronto para o trabalho.

Verificação do status de migração

Primeiro, verifique se a migração foi bem-sucedida ou se falhou.

A maneira como você verifica o status da migração depende de como a migração foi executada.

  • Se você executou a migração usando a GitHub CLI, por padrão, o processo exibirá se a migração foi bem-sucedida ou se falhou quando a migração for concluída. Se a migração falhou, você verá o motivo da falha.

    Migration completed (ID: RM_123)! State: SUCCEEDED

  • Se você executou a migração usando a GitHub CLI com o argumento opcional --queue-only, o processo será encerrado imediatamente após o enfileiramento da migração e não informará se a migração foi bem-sucedida ou se falhou. É possível verificar o status de uma migração usando o comando wait-for-migration ou revisando o log de migração.

  • Se você executou a migração usando a API GraphQL, poderá consultar os campos state e failureReason no objeto RepositoryMigration.

Se a migração falhar, o log de migração poderá conter informações adicionais sobre a causa da falha. Para obter mais informações, consulte "Revisar o log de migração".

Como revisar o log de migração

Analise o log de migração para cada repositório migrado. Para obter mais informações, confira "Como acessar os logs de migração do GitHub Enterprise Importer".

Se a migração falhar, o log poderá conter informações adicionais sobre a causa da falha.

Se a migração for bem-sucedida, poderá haver avisos no log de migração representando partes específicas dos dados (por exemplo, pull requests, problemas ou comentários) que não foram migrados ou foram migrados com advertências.

Para obter mais informações sobre como entender avisos de migração, consulte "Solução de problemas de migração com o GitHub Enterprise Importer". Depois de revisar os avisos de migração, você precisará tomar uma decisão sobre se pode aceitar esses avisos e seguir em frente.

Como migrar objetos do Git LFS

O GitHub Enterprise Importer não migra objetos do Git LFS. Se o repositório de origem usar o Git LFS, você poderá enviar objetos do Git LFS de modo manual para o repositório migrado localmente. Para obter mais informações, confira "Duplicar um repositório".

Definir a visibilidade do repositório

Todos os repositórios são migrados como privados por padrão, e somente o usuário que executou a migração e os proprietários da organização terão acesso ao repositório. Se você não quiser que o repositório seja particular, altere a visibilidade.

  • Você pode definir a visibilidade de um repositório com a opção --target-repo-visibility da CLI ou a propriedade targetRepoVisibility do GraphQL.
  • Você pode alterar a visibilidade de um repositório no navegador. Para obter mais informações, confira "Definir a visibilidade do repositório".
  • Como alternativa, você pode usar a GitHub CLI para alterar a visibilidade do repositório na linha de comando. Você pode até adicionar esse comando ao script que foi gerado para executar suas migrações. Para obter mais informações, confira "gh repo edit" na documentação da GitHub CLI.

Como configurar o GitHub Actions

Se você usar o GitHub Actions em um repositório, seus fluxos de trabalho serão migrados automaticamente como parte do repositório Git.

Durante o processo de migração, o GitHub Actions é desabilitado para todos os repositórios migrados para evitar que fluxos de trabalho sejam disparados acidentalmente, mas o GitHub Actions é habilitado novamente quando a migração é concluída.

Se você estava usando executores auto-hospedados executor maiors ou segredos criptografados, você precisará reconfigurá-los.

Observação: o histórico de execuções de fluxo de trabalho do GitHub Actions não é incluído nas migrações.

  1. Se você usar executores auto-hospedados, reconfigure os executores.

  2. Se você usar executor maiors, reconfigure seus executores.

  3. Adicione novamente os segredos criptografados.

  4. Reconfigure os ambientes. Para obter mais informações, confira "Gerenciar ambientes para implantação".

Como configurar listas de IPs permitidos

Se você adicionou os intervalos de IP do GitHub Enterprise Importer às listas de IPs permitidos das organizações de origem ou de destino, remova essas entradas. Se você desabilitou as restrições de lista de IPs permitidos do provedor de identidade para a empresa de destino, habilite-as novamente agora.

Para obter mais informações, confira "Gerenciando o acesso para uma migração entre produtos GitHub".

Gerenciar GitHub Advanced Security

Se você habilitou o GitHub Advanced Security para a organização de destino antes de migrar os repositórios, as configurações dos recursos individuais foram migradas. Caso contrário, você precisará habilitar novamente os recursos individuais após a migração. Para obter mais informações, confira "Gerenciando as configurações de segurança e análise do repositório".

Há etapas adicionais pós-migração para cada recurso.

Secret scanning

Quando a verificação de segredos estiver habilitada para o repositório de destino, uma verificação de todo o repositório será executada. Depois que a verificação for concluída, todos os alertas serão preenchidos, mas sem estados de correção.

Você pode usar a API REST para atualizar os alertas a fim de espelhar as correções no repositório de origem. Para obter mais informações, confira "Pontos de extremidade da API REST para verificação de segredos".

O usuário associado a essas correções atualizadas será o usuário proprietário do personal access token que foi usado para as chamadas à API, não o usuário que corrigiu o alerta no repositório de origem, e a data associada à correção será a data da chamada à API, não a data em que o alerta foi corrigido no repositório de origem.

Code scanning

Os alertas da Code scanning não são migrados pelo GitHub Enterprise Importer. No entanto, os alertas ficam disponíveis como dados SARIF no repositório de origem. Você pode usar a API REST para carregar esses dados no repositório de destino. Para obter mais informações, confira "Pontos de extremidade da API REST para varredura de código".

Os alertas da Code scanning preenchidos dessa forma serão diferentes dos alertas originais no repositório de origem.

  • Os alertas só incluirão a detecção e o estado mais recente do alerta, não toda a linha do tempo do repositório de origem.
  • Os alertas só serão identificados como open ou fixed. Outros estados de correção, como dismissed e reopened, serão perdidos.
  • As datas de todos os eventos no alerta serão a data da chamada à API, não as datas em que os eventos ocorreram originalmente no repositório de origem.
  • Todos os atores, como o criador do alerta, serão alterados para o proprietário do personal access token usado para a chamada à API.

Dependabot alerts

Quando os Dependabot alerts e o grafo de dependência estiverem habilitados, os Dependabot alerts serão recompilados com base no estado atual do branch padrão. Os estados de correção desses alertas não são migrados, e os alertas anteriores também não são migrados.

Você precisará adicionar novamente todos os segredos criptografados do Dependabot Para obter mais informações, confira "Configurando o acesso a registros privados para Dependabot".

Como habilitar webhooks

Todos os webhooks ativos no repositório de origem são migrados. No entanto, os webhooks migrados serão desabilitados por padrão. Você pode habilitar novamente esses webhooks nas configurações do repositório.

  1. Navegue até as configurações do repositório migrado.
  2. Na seção "Código e automação" da barra lateral, clique em Webhooks.
  3. À direita do webhook que você deseja habilitar, clique em Editar.
  4. Se você estava usando um token secreto para proteger o webhook, em "Segredo", adicione novamente o segredo.
  5. Na parte inferior da página, selecione Ativo.
  6. Clique em Atualizar webhook.

Como reinstalar GitHub Apps

Se você tiver GitHub Apps instalados no repositório de origem, reinstale-os no repositório migrado. Para obter mais informações, confira "Instalando seu próprio Aplicativo GitHub".

Como recriar equipes

Se você usou a migração por organização, basta restabelecer a associação às equipes. Se você usou a migração por repositório, recrie as equipes, permita a essas equipes acesso a repositórios e restabeleça a associação às equipes.

Como recriar equipes para migrações da organização

As equipes e o acesso delas ao repositório são migrados como parte de uma migração da organização, ao contrário da associação à equipe. Após a migração, você precisa adicionar usuários às equipes migradas.

Recomendamos fortemente o uso da sincronização de equipe para gerenciar a associação de equipe por meio do IdP (provedor de identidade). Para obter mais informações, confira "Configurando o provisionamento do SCIM para gerenciar usuários" ou, para empresas que não usam Enterprise Managed Users, "Gerenciando a sincronização de equipes para organizações da sua empresa".

Caso contrário, você pode adicionar membros manualmente à sua organização e adicionar membros da organização às equipes. Para obter mais informações, confira "Adicionar integrantes da organização a uma equipe".

Como recriar equipes para migrações de repositório

As equipes não são migradas como parte de uma migração de repositório. Você precisa recriar manualmente as equipes e permitir a cada equipe acesso ao repositório.

  1. Recrie as equipes. Para obter mais informações, confira "Criar equipes".
  2. Adicione membros da organização às equipes. Para obter mais informações, confira "Adicionar integrantes da organização a uma equipe".
  3. Forneça a cada equipe acesso ao repositório. Para obter mais informações, confira "Gerenciar o acesso da equipe em um repositório da organização".

Como recuperar manequins

Depois que você executar uma migração com o GitHub Enterprise Importer, todas as atividades do usuário no repositório migrado (exceto os commits do Git) são atribuídas a identidades de espaço reservado chamadas manequins.

Você pode atribuir novamente o histórico de cada manequim a um membro da organização com a GitHub CLI ou em seu navegador. Se você usar a GitHub CLI, poderá recuperar manequins em massa. Para obter mais informações, confira "Como recuperar manequins no GitHub Enterprise Importer".

Observação: somente os proprietários da organização podem recuperar manequins. Se você recebeu a função de migrador, entre em contato com um proprietário da organização para executar esta etapa.

  1. Decida se deseja recuperar os manequins.
  2. Planeje quando concluirá as recuperações.
  3. Recupere os manequins.
  4. Se um dos membros ainda não tiver o acesso apropriado ao repositório por meio da associação a uma equipe, permita aos membros acesso ao repositório. Para obter mais informações, confira "Gerenciar o acesso de um indivíduo a um repositório da organização".