Visão geral de uma migração do Bitbucket Server 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 saber mais, confira Sobre o GitHub Enterprise Importer.

Se você estiver migrando do Bitbucket Server, use este guia para planejar e implementar sua migração e concluir as tarefas de acompanhamento.

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.

• 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 fazer o inventário dos repositórios necessários para a migração, avalie os 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. Determine quantos repositórios e quantas solicitações de pull você precisa migrar.
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 Bitbucket Server, o GitHub Enterprise Importer migra apenas os repositórios Git e as solicitações de pull. Todos os outros ativos, como pipelines de CI, permanecerão no Bitbucket Server.

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

1. Revise os dados migrados do Bitbucket Server. Para saber mais, confira Sobre as migrações do Bitbucket Server 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 no GitHub ou um proprietário da organização precisa conceder a você a função de migrador.

Você também precisa ter as permissões necessárias e o acesso à sua instância do Bitbucket Server:

• Permissões de administrador ou de superadministrador
• Se a instância do Bitbucket Server executar o Linux, acesso SFTP à instância, usando uma chave privada SSH (confira Gerenciar o acesso para uma migração do Bitbucket Server)
• Se a instância do Bitbucket Server executar o Windows, o acesso ao SMB (compartilhamento de arquivos) à instância

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 Gerenciar o acesso para uma migração do Bitbucket Server.
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 Gerenciar o acesso para uma migração do Bitbucket Server.
5. Confirme se o migrador tem permissões de administrador ou de superadministrador e acesso SFTP à sua instância do Bitbucket Server.

Qual estrutura organizacional queremos criar no GitHub?

Em seguida, planeje a estrutura organizacional que você criará no GitHub.

No Bitbucket Server, os repositórios são agrupados em projetos. No GitHub, os repositórios pertencem às organizações. No entanto, você não deve supor que a melhor abordagem é criar uma organização no GitHub por projeto no Bitbucket Server.

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 repositório migrado pertencerá a uma dessas organizações, o que pode resultar em uma lista grande de repositórios não agrupados em cada organização. No entanto, você pode gerenciar o acesso a grupos de repositórios criando equipes no GitHub. Para saber mais, confira Sobre equipes.

Caso você deseje dividir seu esforço de migração em lotes, considere o envio em lote por organização.

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 Gerenciar o acesso para uma migração do Bitbucket Server.
7. Execute as migrações de produção. Para saber mais, confira Como migrar repositórios do GitHub Enterprise Server 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 Bitbucket Server, o GitHub Enterprise Importer não tenta migrar as permissões de repositório do Bitbucket Server.

Para dar acesso aos repositórios migrados, você pode criar equipes e dar a cada equipe acesso ao repositório.

1. Crie equipes. Para saber mais, confira Criar equipes.
2. Adicione membros da organização às equipes. Para saber mais, confira Adicionar integrantes da organização a uma equipe.
3. Forneça a cada equipe acesso ao repositório. Para saber mais, 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".

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 saber mais, confira Gerenciar o acesso para uma migração do Bitbucket Server.