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

• Recomendamos fortemente que você faça uma execução de avaliação da migração e conclua a migração de produção logo em seguida. Para saber mais sobre execuções de avaliação, confira "Visão geral de uma migração do Bitbucket Server para o GitHub Enterprise Cloud".
• Certifique-se de entender os dados que serão migrados e as limitações de suporte conhecidas do Importador. Para obter mais informações, confira "Sobre as migrações do Bitbucket Server para o GitHub Enterprise Cloud".
• 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 "Gerenciar o acesso para uma migração do Bitbucket Server".
• 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".

Como alternativa, você pode baixar um binário autônomo na página de versões do repositório github/gh-bbs2gh. Você pode executar esse binário diretamente, sem o prefixo gh.

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. Para garantir que você esteja usando a última versão, atualize a extensão.

gh extension upgrade github/gh-bbs2gh

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

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"
     

3. Se você estiver migrando para o GitHub Enterprise Cloud com residência de dados, por questões de conveniência, defina uma variável de ambiente para a URL de API base da sua empresa. Por exemplo:

   Shell

   export TARGET_API_URL="https://api.octocorp.ghe.com"
   

   Você usará essa variável com a opção --target-api-url em comandos executados com a GitHub CLI.

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á de uma chave de acesso da AWS e uma chave secreta com as seguintes permissões:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:ListBucketMultipartUploads",
                "s3:AbortMultipartUpload",
                "s3:ListBucket",
                "s3:DeleteObject",
                "s3:ListMultipartUploadParts"
            ],
            "Resource": [
                "arn:aws:s3:::github-migration-bucket",
                "arn:aws:s3:::github-migration-bucket/*"
            ]
        }
    ]
}

Quando estiver pronto para executar a migração, você precisará fornecer suas credenciais da AWS para a GitHub CLI: região, chave de acesso, chave secreta e token de sessão (se necessário). Você pode transmiti-los como argumentos ou definir variáveis de ambiente chamadas AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY e AWS_SESSION_TOKEN.

Você também precisará transmitir o nome do bucket do S3 usando o argumento --aws-bucket-name.

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.

Como permitir o acesso à rede

Se você configurou regras de firewall na sua conta de armazenamento, verifique se permitiu o acesso aos intervalos de IP para o destino de migração. Confira "Gerenciar o acesso para uma migração do Bitbucket Server".

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 do computador local. (Você precisará excluir o arquivo do provedor de armazenamento de blobs manualmente depois que a migração for concluída.)

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 \
  # If you are migrating to GHE.com:
  --target-api-url TARGET-API-URL
  # If your Bitbucket Server instance runs on Linux:
  --ssh-user SSH-USER --ssh-private-key PATH-TO-KEY
  # If your Bitbucket Server instance runs on Windows:
  --smb-user SMB-USER
  # If you're using AWS S3 as your blob storage provider:
  --aws-bucket-name AWS-BUCKET-NAME
  # If you are running a Bitbucket Data Center cluster or your Bitbucket Server is behind a load balancer:
  --archive-download-host ARCHIVE-DOWNLOAD-HOST

gh bbs2gh migrate-repo --bbs-server-url BBS-SERVER-URL \
  --bbs-project PROJECT --bbs-repo CURRENT-NAME \
  --github-org DESTINATION --github-repo NEW-NAME \
  # If you are migrating to GHE.com:
  --target-api-url TARGET-API-URL
  # If your Bitbucket Server instance runs on Linux:
  --ssh-user SSH-USER --ssh-private-key PATH-TO-KEY
  # If your Bitbucket Server instance runs on Windows:
  --smb-user SMB-USER
  # If you're using AWS S3 as your blob storage provider:
  --aws-bucket-name AWS-BUCKET-NAME
  # If you are running a Bitbucket Data Center cluster or your Bitbucket Server is behind a load balancer:
  --archive-download-host ARCHIVE-DOWNLOAD-HOST

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

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

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.

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 \
  --bbs-server-url BBS-SERVER-URL \
  --bbs-project PROJECT \
  --bbs-repo CURRENT-NAME \
  # If you're using AWS S3 as your blob storage provider:
  --aws-bucket-name AWS-BUCKET-NAME
  # If you are migrating to GHE.com:
  --target-api-url TARGET-API-URL

gh bbs2gh migrate-repo --archive-path ARCHIVE-PATH \
  --github-org DESTINATION --github-repo NEW-NAME \
  --bbs-server-url BBS-SERVER-URL \
  --bbs-project PROJECT \
  --bbs-repo CURRENT-NAME \
  # If you're using AWS S3 as your blob storage provider:
  --aws-bucket-name AWS-BUCKET-NAME
  # If you are migrating to GHE.com:
  --target-api-url TARGET-API-URL

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

Cancelar uma migração

Se você quiser cancelar uma migração, use o comando abort-migration, substituindo MIGRATION-ID pelo ID retornado de migrate-repo.

gh bb2gh abort-migration --migration-id MIGRATION-ID

gh bb2gh abort-migration --migration-id MIGRATION-ID

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 \
  # If you are migrating to GHE.com:
  --target-api-url TARGET-API-URL
  # If your Bitbucket Server instance runs on Linux:
  --ssh-user SSH-USER --ssh-private-key PATH-TO-KEY
  # If your Bitbucket Server instance runs on Windows:
  --smb-user SMB-USER
  # If you are running a Bitbucket Data Center cluster or your Bitbucket Server is behind a load balancer:
  --archive-download-host ARCHIVE-DOWNLOAD-HOST

gh bbs2gh generate-script --bbs-server-url BBS-SERVER-URL \
  --github-org DESTINATION \
  --output FILENAME \
  # If you are migrating to GHE.com:
  --target-api-url TARGET-API-URL
  # If your Bitbucket Server instance runs on Linux:
  --ssh-user SSH-USER --ssh-private-key PATH-TO-KEY
  # If your Bitbucket Server instance runs on Windows:
  --smb-user SMB-USER
  # If you are running a Bitbucket Data Center cluster or your Bitbucket Server is behind a load balancer:
  --archive-download-host ARCHIVE-DOWNLOAD-HOST

Caso você deseje que o script baixe o log de migração para cada repositório migrado, adicione o sinalizador --download-migration-logs. Para obter mais informações sobre os logs de migração, confira "Como acessar os logs de migração do GitHub Enterprise Importer".

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

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.

Se você baixou BBS2GH como um binário autônomo e não como uma extensão para GitHub CLI, será necessário atualizar o script gerado para executar o binário em vez de gh bbs2gh.

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_ID: a ID da chave de acesso para o bucket
  • AWS_SECRET_ACCESS_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.

Só há suporte para cadeias de conexão que usam chaves de acesso da conta de armazenamento. Não há suporte para cadeias de conexão que usam SAS (assinaturas de acesso compartilhado). Para obter informações sobre as chaves de acesso da conta de armazenamento, confira Gerenciar chaves de acesso da conta de armazenamento na documentação do Azure.

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