Como planejar sua migração para o GitHub

Sobre migrações

Se estiver migrando entre produtos do GitHub, como do GitHub Enterprise Server para o GitHub Enterprise Cloud ou de outra plataforma de hospedagem de código, como o Bitbucket Server ou o GitLab, para o GitHub, o ideal será levar seu trabalho com você: o código, o histórico do código e todas as conversas e colaborações anteriores.

Este guia ajudará você a planejar e executar uma migração bem-sucedida. Você aprenderá a se preparar para uma migração, conhecerá as ferramentas disponíveis para migrar seus dados e saberá como fazer da migração um sucesso.

Terminologia de migração

Antes de usar este guia para planejar sua migração, conheça estes termos importantes.

Termo	Definição
Plataforma de hospedagem de código	A ferramenta online que você usa para hospedar seus repositórios de código-fonte e colaborar, como GitHub Enterprise Cloud, Servidor GitHub Enterprise ServerBitbucket e GitLab.com.
VCS (sistema de controle de versão)	A ferramenta usada para controlar e gerenciar alterações no código-fonte no computador em que você está fazendo as alterações. Por exemplo, se você estiver usando GitHub ou o GitLab como sua plataforma de hospedagem de código, você estará usando o sistema de controle de versão do Git. Se estiver usando o Azure DevOps como a plataforma de hospedagem de código, use o Git ou o TFVC (Controle de Versão do Team Foundation) como o sistema de controle de versão subjacente. Também é possível que você não esteja usando um VCS.
Origem da migração	O local do qual você está migrando. Normalmente, essa será uma plataforma de hospedagem de código, mas pode ser seu próprio computador ou uma unidade de rede compartilhada.
Destino da migração	O GitHub produto para o qual você está migrando.
Caminho de migração	A combinação da origem da migração e do destino de migração, como "Bitbucket Server para GitHub Enterprise Cloud". Para determinados caminhos de migração, GitHub oferece ferramentas especializadas, como GitHub Enterprise Importer, para ajudá-lo a migrar.

Como definir o escopo de migração

Para planejar a migração, você precisa entender o que deseja migrar e quando.

Como definir a origem e o destino

Primeiro, determine o local de onde precisa mover os dados. Em geral, isso é, mas nem sempre, uma plataforma de hospedagem de código.

Sua plataforma de hospedagem de código pode ser um produto GitHub, como GitHub.com ou GitHub Enterprise Server, ou pode ser outra plataforma de hospedagem de código, como o Bitbucket Server, GitLab ou Azure DevOps. Dependendo do tamanho e da complexidade da sua empresa, você pode usar várias plataformas de hospedagem de código diferentes.

Se não estiver usando uma plataforma de hospedagem de código, poderá armazenar o código em uma unidade de rede compartilhada, por exemplo.

Onde quer que o código esteja, essa é a "origem da migração".

Você também precisará saber para qual GitHub produto está migrando ou seu "destino de migração". Isso pode ser GitHub.com, GHE.comou GitHub Enterprise Server.

Como criar um inventário básico dos repositórios que você deseja migrar

Depois de identificar a origem e o destino da migração, estabeleça quais dados você precisa migrar.

Você deve criar um inventário de migração com uma lista de todos os repositórios que estão nas suas origens de migração e que você precisa migrar. Recomendamos usar uma planilha. Como ponto de partida, você deve registrar os seguintes dados para cada repositório:

• Nome
• Proprietário: em GitHub, isso seria uma organização, mas em outras ferramentas, pode haver um tipo diferente de proprietário
• URL
• Última atualização do registro de data e hora
• Número de solicitações de pull (ou o equivalente na origem da migração)
• Número de problemas (ou o equivalente na origem da migração)

Se você estiver migrando de GitHub Enterprise Cloud ou GitHub Enterprise Server, poderá obter esses dados com a extensão gh-repo-stats para o GitHub CLI. Com apenas alguns comandos, gh-repo-stats se conectará à API da origem da migração e criará um CSV com todos os campos recomendados. Para obter mais informações, confira o repositório mona-actions/gh-repo-stats repository.

Se você estiver migrando do Bitbucket Server ou do Bitbucket Data Center, recomendamos o inventory-report comando no BBS2GH extension of the GitHub CLI. O comando inventory-report usará a API da instância do Bitbucket para criar um CSV simples. Para obter mais informações sobre como instalar o BBS2GH extension of the GitHub CLI, consulte Como migrar repositórios do Bitbucket Server para o GitHub Enterprise Cloud.

Para outras origens de migração, crie seu inventário de migração por conta própria. Você pode criar a planilha usando as ferramentas de relatório da origem, se disponíveis, ou a API, ou pode criar o inventário manualmente.

Qualquer abordagem que você escolher para o inventário de migração, anote o processo seguido ou os comandos executados. É muito provável que você queira executar novamente o inventário enquanto continua planejando a migração.

Depois de ter uma lista de todos os seus repositórios, decida quais deseja migrar. Uma opção é migrar absolutamente tudo. No entanto, uma migração é uma ótima oportunidade para avaliar seus repositórios e remover qualquer um que não seja mais necessário. Descobrimos que muitas empresas têm centenas ou até milhares de repositórios não utilizados e desnecessários, e arquivá-los pode tornar a migração muito mais simples.

Como medir os tamanhos dos repositórios

Depois de concluir o inventário de migração básico, colete informações sobre o tamanho dos repositórios. Se os repositórios forem grandes ou contiverem arquivos individuais acima de 100 MB, isso poderá tornar a migração mais longa e arriscada e limitar as ferramentas de migração disponíveis para você.

Se você estiver usando o Git como o sistema de controle de versão, não serão apenas os arquivos grandes atualmente no repositório que serão importantes; os arquivos grandes no histórico do repositório também. Por exemplo, se você tinha um arquivo maior que 100 MB no seu repositório no passado, esse arquivo ainda está presente no histórico do Git, a menos que você tenha reescrito o histórico para remover todos os rastreamentos do arquivo. Para obter mais informações sobre como reescrever o histórico, confira Sobre arquivos grandes no GitHub.

Se você usou gh-repo-stats para criar o inventário, você já tem algumas informações básicas sobre o tamanho dos repositórios. Para criar um inventário de migração completo, você precisará obter mais detalhes sobre os dados contidos nos repositórios.

Em seguida, siga as instruções abaixo para adicionar os seguintes dados ao inventário de migração para cada repositório:

• O tamanho do maior arquivo (também conhecido como “blob”)
• O tamanho total de todos os arquivos (“blobs”)

Se estiver usando um sistema de controle de versão diferente do Git ou se os arquivos não forem controlados com um sistema de controle de versão, primeiro, mova os repositórios para o Git. Para saber mais, confira Adicionando o código localmente hospedado no GitHub.

Em seguida, use a ferramenta de código aberto, git-sizer, para obter esses dados para o repositório.

Pré-requisitos

1. Instale git-sizer. Para obter mais informações, confira o repositório github/git-sizer.
2. Para verificar se o git-sizer está instalado, execute git-sizer –version. Se você vê uma saída como git-sizer release 1.5.0, a instalação foi bem-sucedida.
3. Instale jq. Para obter mais informações, confira Baixar jq na documentação jq.
4. Para verificar se o jq está instalado, execute jq –-version. Se você vê uma saída como jq-1.6, a instalação foi bem-sucedida.

Como medir o tamanho do repositório com git-sizer

1. Para clonar o repositório da origem da migração, execute git clone --mirror.
2. Navegue até o diretório em que você clonou o repositório.
3. Para obter o tamanho do maior arquivo no repositório em bytes, execute git-sizer --no-progress -j | jq ".max_blob_size".
4. Para obter o tamanho total de todos os arquivos no repositório em bytes, execute git-sizer --no-progress -j | jq ".unique_blob_size".
5. Adicione os valores das etapas anteriores ao inventário.

Sobre os tipos de migração

Há três abordagens que você pode adotar ao executar uma migração, que fornecem diferentes níveis de fidelidade de migração.

Tipo de migração	Definição	Requisitos
Instantâneo de origem	Migre o estado atual do código, como ele é hoje, mas não inclua nenhum dos históricos de revisões.	Possível para cada origem e destino, mesmo que seu código não esteja atualmente rastreado em um sistema de controle de versão (VCS).
Origem e histórico	Migre o estado atual do código e o histórico de revisões.	Possível se você controla as alterações no Git ou em um sistema de controle de versão que possa ser convertido no Git antes da migração.
Origem, histórico e metadados	Migre o estado atual do código e o histórico de revisões, além do histórico de colaboração, como problemas e solicitações de pull e configurações.	Exige ferramentas especializadas, que não estão disponíveis para todos os caminhos de migração.

Ao decidir qual tipo de migração deve ser concluída, considere as necessidades da sua organização e as ferramentas disponíveis.

O ideal é usar estratégias diferentes para repositórios diferentes. Por exemplo, você pode ter alguns repositórios antigos e arquivados em que o histórico não é importante, enquanto uma migração de alta fidelidade é essencial para o código mais ativo.

Sobre nossos diferentes modelos de suporte de migração

Você pode optar por concluir uma "migração de autoatendimento", na qual planeja e executa sua própria migração usando apenas nossa documentação, sem qualquer suporte profissional.GitHub

Como alternativa, você pode preferir trabalhar com a equipe de Serviços Especializados do GitHub ou com um parceiro GitHub, que chamamos de "migração liderada por especialistas". Com uma migração liderada por especialistas, você se beneficia do conhecimento e da experiência de um especialista que já executou dezenas ou até mesmo centenas de migrações e obtém acesso a ferramentas de migração adicionais que não estão disponíveis para autoatendimento.

Se você estiver migrando um grande volume de dados, provavelmente se beneficiará de uma migração liderada por especialistas. Por exemplo, caso esteja migrando milhares de repositórios ou tenha repositórios complexos com mais de 5 GB de tamanho, recomendamos entrar em contato com os Serviços Especializados.

Para saber mais sobre as migrações lideradas por especialistas, entre em contato com seu representante de conta ou com os Serviços Especializados.

Como decidir as ferramentas que serão usadas

          Para planejar sua migração, leve em consideração o destino e a origem. São essas considerações que determinam o caminho para a migração. Para obter mais informações, consulte [AUTOTITLE](/migrations/overview/migration-paths-to-github).

Como projetar a estrutura da sua organização para o destino da migração

Em GitHub, cada repositório pertence a uma organização. As organizações são contas compartilhadas nas quais empresas e projetos de código aberto podem colaborar em diversas iniciativas ao mesmo tempo, com recursos administrativos e de segurança sofisticados. Para obter mais informações, consulte Sobre organizações.

Se você estiver adotando GitHub pela primeira vez ou já usando GitHub, tire um momento para considerar a estrutura mais eficaz para suas organizações e repositórios após a migração. O design escolhido pode maximizar a colaboração e a descoberta e minimizar a carga administrativa ou pode criar silos desnecessários e sobrecarga administrativa.

Recomendamos minimizar o número de organizações e estruturá-las de acordo com um dos cinco arquétipos. Para obter diretrizes, confira Práticas recomendadas para organizar o trabalho em sua empresa.

Como executar uma simulação de migração para cada repositório

Antes de continuar o planejamento, execute uma migração de teste que inclua todos os repositórios. As simulações abrangentes permitem que você:

• Verifique se a ferramenta escolhida funciona para seus repositórios
• Confirme se a ferramenta atende aos seus requisitos
• Entenda exatamente quais dados serão migrados e quais dados não serão migrados
• Entenda quanto tempo a migração levará para ajudar você a agendar a migração de produção

Não há nada de único em uma simulação de migração. Basta executar uma migração normal e excluir o repositório no destino da migração.

Como planejar as etapas de pré-migração e pós-migração

Migrar os repositórios é apenas uma etapa em um processo de migração maior. Haverá outras etapas que você precisará executar e, possivelmente, dados ou configurações que você precisará migrar manualmente.

A lista completa de etapas necessárias para a migração dependerá de circunstâncias exclusivas, mas há algumas etapas de pré-migração que se aplicam a todas as migrações:

• Informe os usuários antecipadamente sobre a migração futura e a linha do tempo
• Envie lembretes pouco antes da migração ocorrer
• Configurar contas de usuário em GitHub para sua equipe
• Envie instruções aos usuários sobre como atualizar os repositórios locais para apontá-los para o novo sistema

Também há etapas de pós-migração que se aplicam a todas as migrações:

• Informe os usuários de que a migração foi concluída
• Vincule a atividade aos usuários no destino da migração
• Desative a origem da migração

Estas são algumas outras etapas que você deve considerar ao planejar sua migração.

Como migrar a CI (integração contínua) e a CD (entrega contínua)

Se você estiver alternando entre produtos GitHub, já está usando GitHub Actions CI/CD e continuará a usar GitHub Actions, não há muito mais o que fazer. Os arquivos de fluxo de trabalho nos repositórios serão migrados automaticamente para você. Se você usar corredores auto-hospedados, precisará configurá-los em sua nova GitHub organização, para que eles estejam prontos para executar seus fluxos de trabalho.

Se você não estiver usando GitHub Actions, a situação será mais complicada. Se você planeja continuar usando o mesmo provedor de CI/CD, precisará verificar se o provedor é compatível com GitHub e conectar o provedor à sua nova organização e repositórios.

Se você estiver planejando mudar para GitHub Actions, não recomendamos fazer isso ao mesmo tempo em que você migra seus repositórios. Em vez disso, aguarde até uma data posterior e execute a migração de CI/CD como uma etapa separada. Isso tornará o processo de migração mais gerenciável. Quando estiver pronto para a migração, confira Migrar para o GitHub Actions.

Como migrar as integrações

É provável que você esteja usando integrações com seu provedor de hospedagem de código, desenvolvidas internamente ou fornecidas por outros fornecedores.

Se você já estiver usando GitHub, precisará reconfigurar suas integrações para apontar para suas novas organizações e repositórios. Se a integração for fornecida por um fornecedor, entre em contato com o fornecedor para obter instruções. Se a integração foi desenvolvida internamente, reconfigure-a na sua nova organização, gerando novos tokens e chaves.

Se você é novo em GitHub, verifique se as suas integrações são compatíveis com GitHub, e então reconfigure-as. Se você usar integrações que foram desenvolvidas internamente, escreva-as novamente para trabalhar com a GitHub API. Para saber mais, confira documentação da API REST GitHub.

Vinculando atividade aos usuários no destino da migração

Se você estiver migrando o histórico de colaboração ou de metadados, bem como o código, vincule a atividade dos usuários às novas identidades no destino da migração.

Por exemplo, suponha que @octocat tenha criado uma questão em sua instância do GitHub Enterprise Server, e você esteja mudando para GitHub Enterprise Cloud. Em GitHub Enterprise Cloud, @octocat pode ter um nome de usuário completamente diferente. O processo de atribuição permite vincular a atividade do usuário a essas novas identidades.

A maneira como a atribuição funciona é diferente entre as ferramentas:

• Se você estiver usando ghe-migrator, gl-exporterou bbs-exporter, decidirá como deseja atribuir os dados antecipadamente e incluirá um arquivo de mapeamento ao importar os dados.
• Se você estiver usando GitHub Enterprise Importer ou Enterprise Live Migrations, os dados serão vinculados a identidades de espaço reservado chamadas "manequins" e você poderá atribuir esse histórico a usuários reais após a migração dos dados. Para saber mais, confira Como recuperar manequins no GitHub Enterprise Importer.

Como gerenciar equipes e permissões

A maioria dos clientes usa equipes para gerenciar o acesso aos repositórios. Com as equipes, em vez de dar acesso Mona a um repositório diretamente, você pode adicionar a Mona à equipe de Engenharia e permitir a todos da equipe de Engenharia acesso ao repositório. Para saber mais, confira Sobre as equipes da organização.

Você pode criar suas equipes e adicionar membros da equipe antes de migrar os repositórios. Você pode querer gerenciar seus membros por meio do IdP (provedor de identidade) vinculando suas equipes a grupos de IdP. Para saber mais, confira Sincronizar uma equipe com um grupo de provedor de identidade.

No entanto, só será possível anexar as equipes aos repositórios após a migração dos repositórios.