Como migrar repositórios do GitHub Enterprise Server para o GitHub Enterprise Cloud

Sobre as migrações de repositório com o GitHub Enterprise Importer

Você pode migrar repositórios individuais ou todos os repositórios de uma instância do Bitbucket Server usando a GitHub CLI.

No momento, não há suporte para a migração do Bitbucket Server com a API do GitHub.

Pré-requisitos

• Para garantir que você entendeu as limitações de suporte conhecidas do Importer, leia "Sobre o GitHub Enterprise Importer".
• We strongly recommend that you perform a trial run of your migration and complete your production migration soon after. To learn more about trial run best practices, see "Como se preparar para executar uma migração com o GitHub Enterprise Importer."
• Embora não seja necessário, recomendamos interromper o trabalho durante a migração de produção. O Importer não dá suporte a migrações delta, ou seja, as alterações que ocorrerem durante a migração não serão migradas. Se você optar por não interromper o trabalho durante a migração de produção, precisará migrar manualmente essas alterações.
• Para a organização de destino no GitHub.com, você precisa ser um proprietário da organização ou ter a função de migrador. Para obter mais informações, confira "Como conceder a função de migrador ao GitHub Enterprise Importer".
• Você precisa ter o nome de usuário e a senha de uma conta do Bitbucket Server com permissões de administrador ou de superadministrador.

Etapa 1: Instalar a BBS2GH extension of the GitHub CLI

Se essa for sua primeira migração, você precisará instalar a BBS2GH extension of the GitHub CLI. Para obter mais informações sobre a GitHub CLI, confira "Sobre o a CLI do GitHub".

1. Instale a GitHub CLI. Para obter instruções de instalação para GitHub CLI, veja o repositório GitHub CLI.

   Observação: você precisa ter a versão 2.4.0 ou mais recente da GitHub CLI. Verifique a versão instalada com o comando gh --version.

2. Instale a BBS2GH extension.

   Shell

   gh extension install github/gh-bbs2gh

Sempre que precisar de ajuda com a BBS2GH extension, use o sinalizador --help com um comando. Por exemplo, gh bbs2gh --help listará todos os comandos disponíveis, e gh bbs2gh migrate-repo --help listará todas as opções disponíveis para o comando migrate-repo.

Etapa 2: Atualizar a BBS2GH extension of the GitHub CLI

A BBS2GH extension of the GitHub CLI é atualizada semanalmente. To make sure you're using the latest version, update the extension.

gh extension upgrade github/gh-bbs2gh

Etapa 3: Definir variáveis de ambiente

Para usar a BBS2GH extension para migrar para o GitHub Enterprise Cloud, crie um personal access token que possa acessar a organização de destino e defina o personal access token como uma variável de ambiente.

Você também precisará definir variáveis de ambiente para seu nome de usuário e sua senha do Bitbucket Server e, se a instância do Bitbucket Server for executada no Windows, sua senha do SMB.

1. Crie e registre um personal access token (classic) que será autenticado para a organização de destino no GitHub Enterprise Cloud, verificando se o token atende a todos os requisitos. Para obter mais informações, confira "Como gerenciar o acesso do GitHub Enterprise Importer".

2. Defina variáveis de ambiente substituindo TOKEN pelo personal access token que você registrou acima, USERNAME pelo nome de usuário de uma conta do Bitbucket Server que tenha permissões de administrador ou de superadministrador e PASSWORD pela senha da conta do Bitbucket Server.

   • Se você estiver usando o Terminal, use o comando export.

     Shell

     export GH_PAT="TOKEN"
     export BBS_USERNAME="USERNAME"
     export BBS_PASSWORD="PASSWORD"
     # If your Bitbucket Server instance runs on Windows
     export SMB_PASSWORD="PASSWORD"

   • Se você estiver usando o PowerShell, use o comando $env.

     Shell

     $env:GH_PAT="TOKEN"
     $env:BBS_USERNAME="USERNAME"
     $env:BBS_PASSWORD="PASSWORD"
     # If your Bitbucket Server instance runs on Windows
     $env:SMB_PASSWORD="PASSWORD"

Etapa 4: Configurar o armazenamento de blobs

Como muitas instâncias do Bitbucket Server são protegidas por firewalls, a GitHub CLI usa o armazenamento de blobs como um local intermediário para armazenar seus dados que podem ser acessados pela Internet.

Primeiro, você vai gerar um arquivo morto dos dados que deseja migrar e enviará os dados por push para o armazenamento de blobs protegido pelo firewall.

A GitHub CLI dá suporte aos seguintes provedores de armazenamento de blobs:

• AWS (Amazon Web Services) S3
• Armazenamento do Blobs do Azure

Para executar uma migração, você precisa configurar um contêiner de armazenamento com o provedor de nuvem escolhido para armazenar seus dados.

Como configurar um bucket de armazenamento da AWS S3

Na AWS, configure um bucket da S3. Para obter mais informações, confira Como criar um bucket na documentação da AWS.

Você também precisará ter uma chave de acesso da AWS e uma chave secreta com acesso read-write ao bucket.

Quando estiver pronto para executar a migração, transmita o nome do bucket, a chave de acesso e a chave secreta para a GitHub CLI como argumentos ou transmita-os usando variáveis de ambiente chamadas AWS_BUCKET_NAME, AWS_ACCESS_KEY e AWS_SECRET_KEY.

Como configurar uma conta de armazenamento do Armazenamento de Blobs do Azure

No Azure, crie uma conta de armazenamento e anote a cadeia de conexão. Para obter mais informações, confira Gerenciar chaves de acesso da conta de armazenamento no Microsoft Docs.

Quando estiver pronto para executar a migração, transmita a cadeia de conexão para a GitHub CLI como um argumento ou usando uma variável de ambiente chamada AZURE_STORAGE_CONNECTION_STRING.

Etapa 5: Migrar um repositório

Você pode migrar repositórios com o comando gh bbs2gh migrate-repo.

Quando você migra um repositório, por padrão, o BBS2GH extension of the GitHub CLI executa as seguintes etapas:

1. Conecta-se à instância do Bitbucket Server e gera um arquivo morto de migração por repositório
2. Baixa o arquivo de migração da instância do Bitbucket Server no computador em que você está executando a BBS2GH extension of the GitHub CLI por meio do SFTP (Linux) ou do SMB (Windows)
3. Carrega os arquivos de migração no provedor de armazenamento de blobs de sua escolha
4. Inicia a migração no GitHub Enterprise Cloud, usando as URLs dos arquivos armazenados com o provedor de armazenamento de blobs
5. Exclui o arquivo de migração

Como alternativa, você pode usar o GitHub CLI para gerar o arquivo morto, baixar esse arquivo manualmente e usar o GitHub CLI para continuar a migração.

• "Permitir que o GitHub CLI baixe o arquivo de migração"
• "Baixar o arquivo morto de migração manualmente"

Permitir que o GitHub CLI baixe o arquivo de migração

Para migrar um repositório individual, use o comando gh bbs2gh migrate-repo.

Siga esta etapa em um computador que possa acessar:

• A instância do Bitbucket Server via HTTPS
• A instância do Bitbucket Server via SFTP, caso ela seja executada no Linux. Em geral, se você puder acessar o servidor por meio do SSH, também poderá usar o SFTP.
• A instância do Bitbucket Server via SMB, caso ela seja executada no Windows
• O provedor de armazenamento de blobs escolhido

gh bbs2gh migrate-repo --bbs-server-url BBS-SERVER-URL \
  --bbs-project PROJECT --bbs-repo CURRENT-NAME \
  --github-org DESTINATION --github-repo NEW-NAME \
  # Use the following options if your Bitbucket Server instance runs on Linux
  --ssh-user SSH-USER --ssh-private-key PATH-TO-KEY
  # Use the following options if your Bitbucket Server instance runs on Windows
  --smb-user SMB-USER
  # Use the following option if you're using AWS S3 as your blob storage provider
  --aws-bucket-name AWS-BUCKET-NAME

Substitua os espaços reservados no comando acima pelos valores a seguir.

Espaço reservado | Valor | ----------- | ----- | BBS-SERVER-URL | A URL da instância do Bitbucket Server PROJECT | A chave para o projeto do Bitbucket Server do repositório que você deseja migrar CURRENT-NAME | O nome do repositório que você deseja migrar DESTINATION | Nome da organização de destino NEW-NAME | O nome que você deseja dar ao repositório migrado SSH-USER | Se a instância do Bitbucket Server for executada no Linux, o nome de usuário a ser usado ao se conectar ao Bitbucket Server via SFTP PATH-TO-KEY | Se a instância do Bitbucket Server for executada no Linux, o caminho para a chave privada SSH, como ~/.ssh/id_rsa. Para ver os requisitos de chave SSH, confira "Como gerenciar o acesso do GitHub Enterprise Importer". SMB-USER | Se a instância do Bitbucket Server for executada no Windows, o nome de usuário a ser usado ao se conectar ao Bitbucket Server via SMB AWS-BUCKET-NAME | The bucket name for your AWS S3 bucket

Baixar o arquivo morto de migração manualmente

Por padrão, o BBS2GH extension of the GitHub CLI executa toda a migração, incluindo o download do arquivo de migração da instância do Bitbucket Server usando SFTP ou SMB.

No entanto, alguns clientes preferem baixar o arquivo de migração manualmente, porque seu servidor não oferece acesso SFTP, por exemplo. Nesse caso, você pode usar o GitHub CLI para gerar o arquivo morto, baixar esse arquivo manualmente e usar o GitHub CLI para continuar a migração.

Siga esta etapa em um computador que possa acessar:

• A instância do Bitbucket Server via HTTPS
• O provedor de armazenamento de blobs escolhido

Primeiro, use o comando gh bbs2gh migrate-repo com apenas os seguintes argumentos:

gh bbs2gh migrate-repo --bbs-server-url BBS-SERVER-URL \
  --bbs-project PROJECT \
  --bbs-repo CURRENT-NAME

Substitua os espaços reservados no comando acima pelos valores a seguir.

Espaço reservado | Valor | ----------- | ----- | BBS-SERVER-URL | A URL da instância do Bitbucket Server PROJECT | A chave para o projeto do Bitbucket Server do repositório que você deseja migrar CURRENT-NAME | O nome do repositório que você deseja migrar

O arquivo de migração será gerado e o caminho será impresso na saída do comando:

[12:14] [INFO] Export completed. Your migration archive should be ready on your
instance at $BITBUCKET_SHARED_HOME/data/migration/export/Bitbucket_export_9.tar

Em geral, $BITBUCKET_SHARED_HOME será definido como /var/atlassian/application-data/bitbucket/shared no Linux e C:\Atlassian\ApplicationData\Bitbucket\Shared no Windows, mas isso pode ser diferente dependendo da configuração do servidor. Para ajudar você a identificar seu diretório inicial compartilhado, confira "Solução de problemas de migração com o GitHub Enterprise Importer".

Baixe o arquivo de migração de sua instância do Bitbucket Server e armazene o arquivo na máquina onde você está executando o GitHub CLI.

Para importar o arquivo de migração para GitHub, use o comando gh bbs2gh migrate-repo novamente, com um conjunto diferente de argumentos:

gh bbs2gh migrate-repo --archive-path ARCHIVE-PATH \
  --github-org DESTINATION --github-repo NEW-NAME \
  # Use the following option if you're using AWS S3 as your blob storage provider
  --aws-bucket-name AWS-BUCKET-NAME

Substitua os espaços reservados no comando acima pelos valores a seguir.

Espaço reservado | Valor | ----------- | ----- | ARCHIVE-PATH | O caminho para o arquivo de migração do Servidor Bitbucket baixado de sua instância DESTINATION | Nome da organização de destino NEW-NAME | O nome que você deseja dar ao repositório migrado AWS-BUCKET-NAME | The bucket name for your AWS S3 bucket

Etapa 6: Validar a migração e verificar o log de erros

Quando a migração for concluída, recomendaremos analisar o log de migração. Para obter mais informações, confira "Como acessar os logs de migração do GitHub Enterprise Importer".

Recomendamos que você analise os repositórios migrados para uma verificação de integridade.

Etapa 7: Migrar vários repositórios

Caso você deseje migrar vários repositórios para o GitHub Enterprise Cloud ao mesmo tempo, use a GitHub CLI para gerar um script de migração. O script resultante conterá uma lista de comandos de migração, um por repositório.

Como gerar um script de migração

Siga esta etapa em um computador que possa acessar a instância do Bitbucket Server via HTTPS.

Para gerar um script de migração, execute o comando gh bbs2gh generate-script.

gh bbs2gh generate-script --bbs-server-url BBS-SERVER-URL \
  --github-org DESTINATION \
  --output FILENAME \
  # Use the following options if your Bitbucket Server instance runs on Linux
  --ssh-user SSH-USER --ssh-private-key PATH-TO-KEY
  # Use the following options if your Bitbucket Server instance runs on Windows
  --smb-user SMB-USER

If you want the script to download the migration log for each migrated repository, add the --download-migration-logs flag. For more information about migration logs, see "Como acessar os logs de migração do GitHub Enterprise Importer."

Substitua os espaços reservados no comando acima pelos valores a seguir.

Espaço reservado | Valor | ----------- | ----- | BBS-SERVER-URL | A URL da instância do Bitbucket Server DESTINATION | Nome da organização de destino FILENAME | Um nome de arquivo para o script de migração resultante

Se estiver usando o Terminal, use uma extensão de arquivo .ps1, pois o script gerado exige a execução do PowerShell. Você pode instalar o PowerShell para Mac ou Linux. SSH-USER | Se a instância do Bitbucket Server for executada no Linux, o nome de usuário a ser usado ao se conectar ao Bitbucket Server via SFTP PATH-TO-KEY | Se a instância do Bitbucket Server for executada no Linux, o caminho para a chave privada SSH, como ~/.ssh/id_rsa. Para ver os requisitos de chave SSH, confira "Como gerenciar o acesso do GitHub Enterprise Importer". SMB-USER | Se a instância do Bitbucket Server for executada no Windows, o nome de usuário a ser usado ao se conectar ao Bitbucket Server via SMB

Como revisar o script de migração

Depois de gerar o script, analise o arquivo e, opcionalmente, edite o script.

• Se houver repositórios que você não deseja migrar, exclua ou remova os comentários das linhas correspondentes.
• Por padrão, os nomes de repositórios do GitHub seguirão uma convenção projectKey-repositoryName. Por exemplo, um repositório do Bitbucket Server chamado airports que faz parte do projeto open-source e que tem a chave OS, será chamado OS-airports no GitHub. Caso você deseje que algum repositório tenha um nome diferente no GitHub, atualize o valor do sinalizador --github-repo correspondente.

Executar o script de migração

Para migrar seus repositórios, execute o script gerado.

Siga esta etapa em um computador que possa acessar:

• A instância do Bitbucket Server via HTTPS
• A instância do Bitbucket Server via SFTP, caso ela seja executada no Linux. Em geral, se você puder acessar o servidor por meio do SSH, também poderá usar o SFTP.
• A instância do Bitbucket Server via SMB, caso ela seja executada no Windows
• O provedor de armazenamento de blobs escolhido

Antes de executar o script, você precisa definir variáveis de ambiente adicionais para se autenticar no provedor de armazenamento de blobs.

• Para a AWS S3, defina as variáveis de ambiente a seguir.
  • AWS_ACCESS_KEY: a chave de acesso para o bucket
  • AWS_SECRET_KEY: a chave secreta do bucket
  • AWS_REGION: a região da AWS em que o bucket está localizado
  • AWS_SESSION_TOKEN: o token de sessão, se você estiver usando credenciais temporárias da AWS (confira Como usar credenciais temporárias com recursos da AWS na documentação da AWS)
• Para o Armazenamento de Blobs do Azure, defina AZURE_STORAGE_CONNECTION_STRING como a cadeia de conexão para sua conta de armazenamento do Azure.

Only connection strings using storage account access keys are supported. Connection strings which use shared access signatures (SAS) are not supported. For more information about storage account access keys, see Manage storage account access keys in the Azure documentation.

Para migrar vários repositórios, execute o script gerado acima. Substitua FILENAME nos comandos abaixo pelo nome do arquivo que você forneceu ao gerar o script.

• Se estiver usando o Terminal, use ./.
  Shell

  ./FILENAME

• Se estiver usando o PowerShell, use .\.
  Shell

  .\FILENAME