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 orientará você no planejamento e na execução de 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 usada para hospedar os repositórios de código-fonte e colaborar, como o GitHub Enterprise Cloud, o GitHub Enterprise Server, o Bitbucket Server e o 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, caso você esteja usando o GitHub ou o GitLab como a plataforma de hospedagem de código, isso indica que o sistema de controle de versão do Git está sendo usado. 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 o computador ou uma unidade de rede compartilhada.
Destino da migração	O produto do GitHub para o qual você está migrando.
Caminho de migração	A combinação da origem da migração e do destino da migração, como “Bitbucket Server para GitHub Enterprise Cloud”. Para alguns caminhos de migração, o GitHub oferece ferramentas especializadas, como o GitHub Enterprise Importer, para ajudar você na migração.

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.

A plataforma de hospedagem de código pode ser um produto do GitHub, como o GitHub.com ou o GitHub Enterprise Server, ou outra plataforma de hospedagem de código, como o Bitbucket Server, o GitLab ou o 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 produto do GitHub está migrando, ou o "destino da migração". Isso pode ser o GitHub.com, o GHE.com ou o 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 nas origens de migração 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: no GitHub, isso será uma organização, mas em outras ferramentas, pode haver um tipo diferente de proprietário
• URL
• Última atualização de carimbo de data/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 estiver migrando do GitHub Enterprise Cloud ou do GitHub Enterprise Server, obtenha esses dados com a extensão gh-repo-stats da 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 Azure DevOps, recomendamos o comando inventory-report no ADO2GH extension of the GitHub CLI. O comando inventory-report se conectará à API do Azure DevOps e criará um CSV simples com alguns dos campos sugeridos acima. Para saber mais sobre como instalar o ADO2GH extension of the GitHub CLI, confira Migrar repositórios do Azure DevOps para o GitHub Enterprise Cloud.

Se você estiver migrando do Bitbucket Server ou do Bitbucket Data Center, recomendamos o comando inventory-report 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 saber mais sobre como instalar o BBS2GH extension of the GitHub CLI, confira Como migrar repositórios do GitHub Enterprise 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 o 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 o jq. Para obter mais informações, confira Baixar o jq na documentação do 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 o código não seja controlado atualmente em um VCS (sistema de controle de versão).
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 migração usando apenas nossa documentação, sem nenhum suporte profissional do GitHub.

Como alternativa, você pode preferir trabalhar com a equipe de Serviços Especializados do GitHub ou com um parceiro do 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, confira Caminhos de migração para o GitHub.

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

No 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, confira Sobre organizações.

Caso esteja adotando o GitHub pela primeira vez ou já use o GitHub, reserve algum tempo para considerar a estrutura mais eficaz para suas organizações e seus 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 estruturar organizações em sua empresa.

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

Antes de continuar planejando, execute uma simulação de migração, incluindo 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
• Configure contas de usuário no 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 se migrando entre produtos do GitHub, já estiver usando o GitHub Actions para a CI/CD e continuará usando o GitHub Actions, não haverá muito o que fazer. Os arquivos de fluxo de trabalho nos repositórios serão migrados automaticamente para você. Se você usar executores auto-hospedados, precisará configurá-los na sua nova organização do GitHub, de modo que eles estejam prontos para executar os fluxos de trabalho.

Se você não estiver usando o GitHub Actions, a situação será mais complicada. Se você pretende continuar usando o mesmo provedor de CI/CD, verifique se ele é compatível com o GitHub e conecte o provedor à nova organização e aos repositórios.

Caso você esteja planejando mudar para o GitHub Actions, não recomendamos fazer isso ao mesmo tempo que 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 já estiver usando o GitHub, precisará reconfigurar as integrações para apontá-las para as novas organizações e os 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ê estiver usando o GitHub pela primeira vez, verifique se as integrações são compatíveis com o GitHub e reconfigure-as. Caso você use integrações que foram desenvolvidas internamente, reescreva-as para trabalhar com a API do GitHub. Para saber mais, confira Documentação da API REST do GitHub.

Como vincular a 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 um problema no sua instância do GitHub Enterprise Server e você esteja migrando para o GitHub Enterprise Cloud. No 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 o GitHub Enterprise Importer, os dados serão vinculados a identidades de espaço reservado chamadas “manequins” e você poderá atribuir esse histórico a usuários reais depois que os dados forem migrados. 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 equipes.

Você pode criar suas equipes e adicionar membros da equipe antes de migrar os repositórios. O ideal é gerenciar os membros por meio do IdP (provedor de identidade) vinculando as 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 depois que você migrar os repositórios.