Visão geral de uma migração do Azure DevOps para o GitHub Enterprise Cloud

Visão geral

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

Se você estiver migrando do ADO (Azure DevOps), use este guia para planejar e implementar sua migração e concluir as tarefas de acompanhamento.

As empresas que migram do ADO para o GitHub normalmente seguem uma abordagem de várias fases.

1. Migrar os repositórios do ADO para o GitHub.
2. Migrar os pipelines do Azure Pipelines para o GitHub Actions.
3. Migrar os ativos restantes, como painéis e artefatos, do ADO para o GitHub.

Este guia orientará você na conclusão da primeira fase, a migração de repositórios para o GitHub, e pressupõe que você esteja usando a ADO2GH extension of the GitHub CLI.

Como planejar a migração

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

• Em quanto tempo precisamos concluir a migração?
• Entendemos o que será migrado?
• Quem executará a migração?
• Qual estrutura organizacional queremos criar no GitHub?

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.

• Número de repositórios
• Número de solicitações de pull

O tempo de migração baseia-se, em grande parte, no número de solicitações de pull 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 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 cinco mil usuários, a migração levará muito 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.

Entendemos o que será migrado?

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

Para as migrações do ADO, o GitHub Enterprise Importer migra apenas os repositórios Git, incluindo as solicitações de pull e algumas políticas de branch. Todos os outros ativos, como pipelines, itens de trabalho, artefatos, planos de teste, versões e painéis, permanecerão no ADO.

Como as permissões do GitHub funcionam de maneira diferente do ADO, o GitHub Enterprise Importer não tenta migrar as permissões de repositório do ADO. Para obter mais informações, confira "Como configurar as permissões".

Os ganchos de serviço não são migrados do ADO, ou seja, você precisará recriá-los separadamente.

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

Quem executará a migração?

Para migrar um repositório, você precisa ser um proprietário da organização de destino ou um proprietário da organização precisa conceder a você a função de migrador.

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 do Azure DevOps".
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 do Azure DevOps".

Qual estrutura organizacional queremos criar no GitHub?

Em seguida, planeje a estrutura organizacional que você criará no GitHub. O ADO e o GitHub têm diferentes maneiras de organizar o trabalho de uma empresa.

• ADO: Organização > projeto de equipe > repositórios
• GitHub: Empresa > organização > repositórios

Depois de migrar para o GitHub, você deve ter apenas uma conta corporativa e um pequeno número de organizações pertencentes a essa empresa. Cada organização do ADO deve corresponder a uma organização individual no GitHub. Não recomendamos criar uma organização no GitHub para cada projeto de equipe no ADO.

Isso poderá resultar em uma lista grande de repositórios desagrupados em cada organização. No entanto, você pode gerenciar o acesso a grupos de repositórios criando equipes. Para obter mais informações, confira "Sobre equipes".

Caso você deseje dividir seu esforço de migração em lotes, a nova estrutura poderá ajudar você a determinar os lotes. Se você tiver mais de uma organização no ADO e os repositórios de cada organização forem lotes de tamanho razoável, considere o envio em lote por organização. Use a GitHub CLI para gerar um script de migração para toda uma organização no ADO.

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.

Recomendamos criar uma organização de teste para usá-la como destino para suas 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. Crie uma organização de teste para as migrações de avaliação.
2. Execute as migrações de avaliação.
3. Conclua as tarefas de acompanhamento descritas abaixo para as migrações de avaliação.
4. Solicite aos usuários que validem os resultados das migrações.
5. Resolva os problemas descobertos pelas migrações de avaliação.
6. 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 do Azure DevOps".
7. Execute as migrações de produção. Para obter mais informações, confira "Migrar repositórios do Azure DevOps para o GitHub Enterprise Cloud".
8. 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
• Como revisar o log de migração
• Definir a visibilidade do repositório
• Como configurar as permissões
• Como recuperar manequins
• Como configurar listas de permissões de IP

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.

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 as permissões

Como as permissões do GitHub funcionam de maneira diferente do ADO, o GitHub Enterprise Importer não tenta migrar as permissões de repositório do ADO.

Se você usar a CLI do ADO2GH, o GitHub Enterprise Importer criará duas equipes no GitHub para cada projeto de equipe no ADO. Cada equipe recebe um nível diferente de acesso a todos os repositórios originados do projeto de equipe.

Equipe	Acesso aos repositórios migrados
Mantenedores do PROJETO-DE-EQUIPE	Mantenedor
Administradores do PROJETO-DE-EQUIPE	Admin

Para dar acesso aos repositórios migrados, você pode adicionar pessoas a essas equipes. Faça isso manualmente no GitHub ou, se optar por vincular as equipes a grupos do AAD (Azure Active Directory) durante a migração, gerenciando a associação a um grupo no AAD. Para obter mais informações sobre como gerenciar a associação à equipe, confira "Adicionar integrantes da organização a uma equipe".

Se você não estiver usando a CLI do ADO2GH ou se precisar de uma configuração de permissões mais avançada do que esse padrão, configure permissões para os repositórios migrados. Você pode modificar o script de migração de acordo com suas necessidades ou configurar as permissões manualmente após a migração. Para obter mais informações sobre como gerenciar o acesso aos repositórios no GitHub, confira "Funções de repositório para uma organização".

1. Decida qual estrutura de permissões você precisa criar no GitHub.
2. Se ela diferente do padrão, faça um plano para configurar a associação e as permissões da equipe.

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

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

Como configurar listas de permissões de IP

Se você adicionou os intervalos de IP do GitHub Enterprise Importer à lista de permissões de IP da sua organização 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 do Azure DevOps".