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
.
-
Instale a GitHub CLI. Para obter instruções de instalação para GitHub CLI, veja o repositório GitHub CLI.
Note
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
. -
Instale a BBS2GH extension.
Shell gh extension install github/gh-bbs2gh
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.
-
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".
-
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"
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"
$env:GH_PAT="TOKEN" $env:BBS_USERNAME="USERNAME" $env:BBS_PASSWORD="PASSWORD" # If your Bitbucket Server instance runs on Windows $env:SMB_PASSWORD="PASSWORD"
-
-
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"
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/*"
]
}
]
}
Note
O GitHub Enterprise Importer não exclui o arquivo da AWS após a conclusão da migração. Para reduzir os custos de armazenamento, recomendamos configurar a exclusão automática do arquivo após um período. Para obter mais informações, confira Como definir a configuração do ciclo de vida em um bucket na documentação da AWS.
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.
Note
O GitHub Enterprise Importer não exclui o arquivo do Armazenamento de Blobs do Azure após a conclusão da migração. Para reduzir os custos de armazenamento, recomendamos configurar a exclusão automática do arquivo após um período. Para obter mais informações, confira Otimizar os custos gerenciando automaticamente o ciclo de vida dos dados 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:
- Conecta-se à instância do Bitbucket Server e gera um arquivo morto de migração por repositório
- 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)
- Carrega os arquivos de migração no provedor de armazenamento de blobs de sua escolha
- Inicia a migração no GitHub Enterprise Cloud, usando as URLs dos arquivos armazenados com o provedor de armazenamento de blobs
- 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.
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 |
TARGET-API-URL | A URL de API base para o subdomínio da sua empresa do GHE.com. Por exemplo: https://api.octocorp.ghe.com . |
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 "Gerenciar o acesso para uma migração do Bitbucket Server". |
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 | O nome do bucket da AWS S3 |
ARCHIVE-DOWNLOAD-HOST | O host a ser usado para se conectar à instância do Servidor bitbucket/Data center por meio de SSH ou SMB. Você só precisará especificar isso se estiver executando um cluster do Data Center do Bitbucket ou o Servidor Bitbucket estiver atrás de um balanceador de carga. |
Note
Se você recebe um erro mencionando Renci.SshNet
, a CLI está tendo problemas para estabelecer uma conexão SFTP com o servidor para baixar o arquivo morto de migração. Para obter mais informações sobre como solucionar esses problemas, confira "Solução de problemas de migração com o GitHub Enterprise Importer".
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.
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 \ --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.
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 |
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 |
AWS-BUCKET-NAME | O nome do bucket da AWS S3 |
TARGET-API-URL | A URL de API base para o subdomínio da sua empresa do GHE.com. Por exemplo: https://api.octocorp.ghe.com . |
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.
Note
Gerar um script produz um script do PowerShell. Se você estiver usando o Terminal, precisará gerar o script com a extensão de arquivo .ps1
e instalar o PowerShell para Mac ou Linux para executá-lo.
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.
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. |
TARGET-API-URL | A URL de API base para o subdomínio da sua empresa do GHE.com. Por exemplo: https://api.octocorp.ghe.com . |
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 "Gerenciar o acesso para uma migração do Bitbucket Server". |
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 |
ARCHIVE-DOWNLOAD-HOST | O host a ser usado para se conectar à instância do Servidor bitbucket/Data center por meio de SSH ou SMB. Você só precisará especificar isso se estiver executando um cluster do Data Center do Bitbucket ou o Servidor Bitbucket estiver atrás de um balanceador de carga. |
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 chamadoairports
que faz parte do projetoopen-source
e que tem a chaveOS
, será chamadoOS-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 bucketAWS_SECRET_ACCESS_KEY
: a chave secreta do bucketAWS_REGION
: a região da AWS em que o bucket está localizadoAWS_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
./FILENAME
-
Se estiver usando o PowerShell, use
.\
.Shell .\FILENAME
.\FILENAME