Migrating from Azure DevOps with GitHub Enterprise Importer

About migrations from Azure DevOps

With GitHub Enterprise Importer, you can migrate to GitHub Enterprise Cloud on a repository-by-repository basis. For more information, see "Sobre o GitHub Enterprise Importer".

If you're migrating from Azure DevOps (ADO), you can use this guide to plan and implement your migration and complete follow-up tasks.

Enterprises who migrate from ADO to GitHub typically follow a multi-phase approach.

1. Migrate repositories from ADO to GitHub.
2. Migrate pipelines from Azure Pipelines to GitHub Actions.
3. Migrate remaining assets, such as boards and artifacts, from ADO to GitHub.

This guide will guide you through completing the first phase, migrating repositories to GitHub, and assumes you're using the ADO2GH extension of the GitHub CLI.

Planning your migration

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

• How soon do we need to complete the migration?
• Do we understand what will be migrated?
• Who will run the migration?
• What organizational structure do we want in GitHub?

How soon do we need to complete the migration?

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 o Analisador de Migração do GitHub. 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.

• Number of repositories
• Number of pull requests

Migration timing is largely based on the number of pull requests in a repository. If you want to migrate 1,000 repositories, and each repository has 100 pull requests on average, and only 50 users have contributed to the repositories, your migration will likely be very quick. If you want to migrate only 100 repositories, but the repositories each have 75,000 pull requests on average, and 5,000 users, the migration will take much longer and require much more planning and testing.

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 o Analisador de Migração do GitHub e analise o 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.

Do we understand what will be migrated?

Ensure that you and your stakeholders understand what data can be migrated by GitHub Enterprise Importer.

For migrations from ADO, GitHub Enterprise Importer only migrates Git repositories, including pull requests and some branch policies. Any other assets, such as pipelines, work items, artifacts, test plans, releases, and dashboards, will remain in ADO.

Because permissions work differently in GitHub than in ADO, GitHub Enterprise Importer does not attempt to migrate repository permissions from ADO. For more information, see "Configuring permissions."

Service hooks are not migrated from ADO, so you will need to recreate them separately.

1. Review the data that's migrated from Azure DevOps. For more information, see "Suporte à migração para o GitHub Enterprise Importer."
2. Make a list of any data that you'll need to manually migrate or recreate.

Who will run the migration?

To migrate a repository, you must be an organization owner for the destination organization, or an organization owner must grant you the migrator role.

1. Decide whether you want an organization owner of the destination organization to perform your migrations, or whether you need to grant the migrator role to someone else.
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 "Como conceder a função de migrador ao GitHub Enterprise Importer".
4. Confirm that the person has correctly configured personal access tokens to meet all the access requirements. For more information, see "Como gerenciar o acesso do GitHub Enterprise Importer."

What organizational structure do we want in GitHub?

Next, plan the organizational structure you'll create in GitHub. ADO and GitHub have different ways of organizing an enterprise's work.

• ADO: Organization > team project > repositories
• GitHub: Enterprise > organization > repositories

After migrating to GitHub, you should have only one enterprise account and a small number of organizations owned by that enterprise. Each organization from ADO should correspond to a single organization on GitHub. We do not recommend creating an organization on GitHub for each team project on ADO.

This may result in a large list of ungrouped repositories within each organization. However, you can manage access to groups of repositories by creating teams. For more information, see "Sobre equipes."

If you want to break your migration effort into batches, the new structure can help you determine your batches. If you have more than one organization in ADO, and each organization's repositories are reasonably sized batches, consider batching by organization. You can use the GitHub CLI to generate a migration script for an entire organization on 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.

Running your migrations

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.

We recommend creating a test organization to use as a destination for your trial migrations. 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. Create a test organization for your trial migrations.
2. Execute as migrações de avaliação. Para obter mais informações, confira "Como se preparar para executar uma migração com o GitHub Enterprise Importer".
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 "Como gerenciar o acesso do GitHub Enterprise Importer".
7. Run your production migrations. For more information, see "Migrar repositórios do Azure DevOps para o GitHub Enterprise Cloud."
8. Opcionalmente, exclua a organização de teste.

Completing follow-up tasks

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.

• Reviewing the migration log
• Setting repository visibility
• Configuring permissions
• Reclaiming mannequins
• Configuring IP allow lists

Reviewing the migration log

Primeiro, 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 algum item específico no repositório não puder ser migrado, você verá um aviso no log de migração.

1. Analise os logs de migração.
2. Analise os avisos de cada log e verifique se nenhum está bloqueando a aceitação da migração. Para obter mais informações, confira "Solução de problemas de migração com o GitHub Enterprise Importer".

Setting repository visibility

Todos os repositórios são migrados como privados, 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 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.

Configuring permissions

Because permissions work differently in GitHub than in ADO, GitHub Enterprise Importer does not attempt to migrate repository permissions from ADO.

If you used the ADO2GH CLI, GitHub Enterprise Importer will create two teams in GitHub for each team project in ADO. Each team is granted a different level of access to all repositories that originated from the team project.

Team	Access to migrated repositories
TEAM-PROJECT-Maintainers	Maintainer
TEAM-PROJECT-Admins	Admin

To give access to migrated repositories, you can add people to these teams. You can do this manually on GitHub, or if you chose to link the teams to Azure Active Directory (AAD) groups during your migration, by managing group membership in AAD. For more information about manually managing team membership, see "Adicionar integrantes da organização a uma equipe."

If you aren't using the ADO2GH CLI, or if you require a permissions configuration that is more advanced than this default, configure permissions for your migrated repositories. You can modify the migration script to suit your needs, or you can manually configure permissions after your migration. For more information about managing access to repositories on GitHub, see "Funções de repositório para uma organização."

1. Decide what permissions structure you require in GitHub.
2. If different than the default, make a plan for setting up team membership and permissions.

Reclaiming mannequins

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 enviando um convite de atribuição com a GitHub CLI ou no 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 "Como gerenciar o acesso de uma pessoa a um repositório da organização".

Configuring IP allow lists

If you added the IP ranges for GitHub Enterprise Importer to the IP allow list for your destination organization, you can remove those entries. Se você desabilitou as restrições de lista de IPs permitidos do provedor de identidade para a empresa de destino, habilite-as novamente agora.

For more information, see "Como gerenciar o acesso do GitHub Enterprise Importer."