Sobre as migrações de repositório com o GitHub Enterprise Importer
Você pode executar a migração com a GitHub CLI ou a API.
A GitHub CLI simplifica o processo de migração e é recomendada para a maioria dos clientes. Os clientes avançados com necessidades de personalização intensiva podem usar a API para criar integrações próprias ao GitHub Enterprise Importer.
Para ver instruções para usar a API, use o alternador de ferramentas na parte superior da página.
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 entre produtos GitHub.
- 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 migrações entre produtos GitHub.
- 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.
- Nas organizações de origem e de destino, você precisa ser um proprietário da organização ou receber a função de migrador. Para saber mais, confira Gerenciando o acesso para uma migração entre produtos GitHub.
- Quando você usa o GitHub Enterprise Server 3.8 ou superior para configurar o armazenamento de blobs, precisa acessar o Console de Gerenciamento.
Etapa 1: Instalar a GEI extension of the GitHub CLI
Se essa for sua primeira migração, você precisará instalar a GEI 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-gei
. Você pode executar o 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 o GEI extension.
Shell gh extension install github/gh-gei
gh extension install github/gh-gei
Sempre que precisar de ajuda com a GEI extension, use o sinalizador --help
com um comando. Por exemplo, gh gei --help
listará todos os comandos disponíveis, e gh gei migrate-repo --help
listará todas as opções disponíveis para o comando migrate-repo
.
Etapa 2: Atualizar a GEI extension of the GitHub CLI
A GEI extension é atualizada semanalmente. Para garantir que você esteja usando a última versão, atualize a extensão.
gh extension upgrade github/gh-gei
Etapa 3: Definir variáveis de ambiente
Para usar a GEI extension para migrar para o GitHub Enterprise Cloud, você precisa criar personal access tokens que possam acessar as organizações de origem e de destino e definir os personal access tokens como variáveis de ambiente.
-
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 saber mais, confira Gerenciando o acesso para uma migração entre produtos GitHub.
-
Crie e registre um personal access token que será autenticado para a organização de origem, verificando se esse token também atende a todos os mesmos requisitos.
-
Defina variáveis de ambiente para o personal access tokens, substituindo TOKEN nos comandos abaixo pelos personal access tokens que você registrou acima. Use
GH_PAT
para a organização de destino eGH_SOURCE_PAT
para a organização de origem.-
Se você estiver usando o Terminal, use o comando
export
.Shell export GH_PAT="TOKEN" export GH_SOURCE_PAT="TOKEN"
export GH_PAT="TOKEN" export GH_SOURCE_PAT="TOKEN"
-
Se você estiver usando o PowerShell, use o comando
$env
.Shell $env:GH_PAT="TOKEN" $env:GH_SOURCE_PAT="TOKEN"
$env:GH_PAT="TOKEN" $env:GH_SOURCE_PAT="TOKEN"
-
-
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 GitHub Enterprise Server são protegidas por firewalls, usamos o armazenamento de blobs como um local intermediário para armazenar seus dados que o GitHub poderá acessar.
Primeiro, você precisa configurar o armazenamento de blobs com um provedor de nuvem compatível. Em seguida, você precisa configurar suas credenciais para o provedor de armazenamento no Console de Gerenciamento ou na GitHub CLI.
Como configurar o armazenamento de blobs com um provedor de nuvem compatível
A GitHub CLI dá suporte aos seguintes provedores de armazenamento de blobs:
- AWS (Amazon Web Services) S3
- Armazenamento do Blobs do Azure
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.
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.
Como configurar suas credenciais do armazenamento de blobs
Depois de configurar o armazenamento de blobs com um provedor de nuvem compatível, você precisa configurar suas credenciais para o provedor de armazenamento no GitHub:
- Se você usar o GitHub Enterprise Server 3.8 ou superior, configure suas credenciais no Console de Gerenciamento.
- Se você usar o GitHub Enterprise Server 3.7 ou inferior, configure as credenciais na GitHub CLI.
Como configurar o armazenamento de blobs no Console de Gerenciamento do sua instância do GitHub Enterprise Server
Note
Você só precisará configurar o armazenamento de blobs no Console de Gerenciamento se usar o GitHub Enterprise Server 3.8 ou superior. Se você usar a versão 3.7 ou inferior, configure suas credenciais na GitHub CLI.
Depois de configurar um bucket de armazenamento da AWS S3 ou uma conta de armazenamento do Armazenamento de Blobs do Azure, configure o armazenamento de blobs no Console de Gerenciamento do sua instância do GitHub Enterprise Server. Para obter mais informações sobre o Console de Gerenciamento, confira Como administrar sua instância no console de gerenciamento.
-
Em uma conta administrativa no GitHub Enterprise Server, no canto superior direito de qualquer página, clique em .
-
Se você ainda não está na página "Administrador do site", no canto superior esquerdo, clique em Administrador do site. 1. Na barra lateral " Administrador do site", clique em Console de Gerenciamento .
-
Faça logon no Console de Gerenciamento.
-
Na barra de navegação superior, clique em Configurações.
-
Em Migrações, clique em Habilitar as Migrações do GitHub .
-
Opcionalmente, para importar as configurações de armazenamento que você definiu para o GitHub Actions, selecione Copiar configurações do Armazenamento em Ações. Para obter mais informações, confira Como habilitar o GitHub Actions com o Armazenamento de Blobs do Azure e Como habilitar o GitHub Actions com o armazenamento da Amazon S3.
Note
Depois de copiar as configurações de armazenamento, talvez ainda seja necessário atualizar a configuração da sua conta de armazenamento em nuvem para trabalhar com o GitHub Enterprise Importer. Em particular, você deve garantir que os endereços IP do GitHub estejam permitidos. Para saber mais, confira Gerenciando o acesso para uma migração entre produtos GitHub.
-
Se você não importar as configurações de armazenamento do GitHub Actions, selecione Armazenamento de Blobs do Azure ou Amazon S3 e preencha os detalhes necessários.
Note
Caso esteja usando o Amazon S3, deverá configurar a "AWS Service URL" como o ponto de extremidade padrão da região da AWS onde seu bucket está localizado. Por exemplo, se o bucket estiver localizado na região
eu-west-1
, a "URL do serviço AWS" seráhttps://s3.eu-west-1.amazonaws.com
. A rede da instância do GitHub Enterprise Server deve permitir o acesso a esse host. Não há suporte para pontos de extremidade de gateway, comobucket.vpce-0e25b8cdd720f900e-argc85vg.s3.eu-west-1.vpce.amazonaws.com
. Para obter mais informações sobre pontos de extremidade de gateway, consulte Pontos de extremidade de gateway d Amazon S3 na documentação da AWS. -
Clique em Testar configurações de armazenamento.
-
Clique em Salvar alterações.
Como configurar suas credenciais do armazenamento de blobs na GitHub CLI
Note
Você só precisará configurar suas credenciais do armazenamento de blobs na GitHub CLI se usar o GitHub Enterprise Server 3.7 ou inferior. Se você usar a versão 3.8 ou superior, configure o armazenamento de blobs no Console de Gerenciamento.
Se você configurar suas credenciais do armazenamento de blobs na GitHub CLI, não poderá executar migrações em que as exportações de metadados ou de origem do Git excedam 2 GB. Para executar essas migrações, atualize para o GitHub Enterprise Server 3.8 ou superior.
Como configurar credenciais da AWS S3 na GitHub CLI
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 credenciais de conta do Armazenamento de Blobs do Azure na GitHub CLI
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 Gerenciando o acesso para uma migração entre produtos GitHub.
Etapa 5: Gerar um script de migração
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.
Caso você deseje migrar um repositório individual, vá para a próxima etapa.
Como gerar um script de migração
Você precisa seguir esta etapa em um computador que possa acessar a API para o sua instância do GitHub Enterprise Server. Se você puder acessar a instância no navegador, o computador terá o acesso correto.
Para gerar um script de migração, execute o comando gh gei generate-script
.
Para o GitHub Enterprise Server 3.8 ou posterior ou se você estiver usando a versão 3.7 ou inferior com o Armazenamento de Blobs do Azure, use os seguintes sinalizadores:
gh gei generate-script --github-source-org SOURCE \ --github-target-org DESTINATION \ --output FILENAME \ --ghes-api-url GHES-API-URL
gh gei generate-script --github-source-org SOURCE \
--github-target-org DESTINATION \
--output FILENAME \
--ghes-api-url GHES-API-URL
Se você estiver usando o GitHub Enterprise Server 3.7 ou inferior com a AWS S3, use os seguintes sinalizadores:
gh gei generate-script --github-source-org SOURCE \ --github-target-org DESTINATION \ --output FILENAME \ --ghes-api-url GHES-API-URL \ --aws-bucket-name AWS-BUCKET-NAME
gh gei generate-script --github-source-org SOURCE \
--github-target-org DESTINATION \
--output FILENAME \
--ghes-api-url GHES-API-URL \
--aws-bucket-name AWS-BUCKET-NAME
Espaços reservados
Substitua os espaços reservados no comando acima pelos valores a seguir.
Espaço reservado | Valor |
---|---|
SOURCE | Nome da organização de origem |
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. |
GHES-API-URL | A URL para a API do sua instância do GitHub Enterprise Server, como https:/ |
AWS-BUCKET-NAME | O nome do bucket da AWS S3 |
Argumentos adicionais
Argument | Descrição |
---|---|
--target-api-url TARGET-API-URL | Se você estiver migrando para o GHE.com, adicione --target-api-url TARGET-API-URL , em que TARGET-API-URL é a URL da API base para o subdomínio da sua empresa. Por exemplo: https:/ . |
--no-ssl-verify | Se o sua instância do GitHub Enterprise Server usar um certificado SSL autoassinado ou inválido, use o sinalizador --no-ssl-verify . Com esse sinalizador, a GitHub CLI vai ignorar a verificação do certificado SSL ao extrair os dados somente da instância. Todas as outras chamadas verificarão o SSL. |
--download-migration-logs | Baixe o log de migração de cada repositório migrado. Para obter mais informações sobre os logs de migração, confira Como acessar os logs de migração do GitHub Enterprise Importer. |
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.
- Caso você deseje que algum repositório tenha um nome diferente na organização de destino, atualize o valor do sinalizador
--target-repo
correspondente. - Se você quiser alterar a visibilidade do novo repositório, atualize o valor do sinalizador
--target-repo-visibility
correspondente. Por padrão, o script define a mesma visibilidade que o repositório de origem.
Se o repositório tiver mais de 10 GB de dados de versões, as versões não poderão ser migradas. Use o sinalizador --skip-releases
para migrar o repositório sem versões.
Se você baixou GEI como um binário autônomo em vez de como uma extensão para o GitHub CLI, será necessário atualizar o script gerado para executar o binário em vez de gh gei
.
Etapa 6: Migrar repositórios
Você pode migrar vários repositórios com um script de migração ou um repositório individual com o comando gh gei migrate-repo
.
Quando você migra repositórios, a GEI extension of the GitHub CLI executa as seguintes etapas:
- Conecta-se ao sua instância do GitHub Enterprise Server e gera dois arquivos de migração por repositório, um para a origem do Git e outro para os metadados
- 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
Migrar vários repositórios
Se você estiver migrando do GitHub Enterprise Server 3.7 ou anterior, antes de executar o script, defina variáveis de ambiente adicionais para se autenticar no provedor de armazenamento de blobs.
-
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 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 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
Migrar um repositório individual
Você precisa seguir esta etapa em um computador que possa acessar a API para o sua instância do GitHub Enterprise Server. Se você puder acessar a instância no navegador, o computador terá o acesso correto.
Para migrar um repositório individual, use o comando gh gei migrate-repo
.
Se você estiver usando o GitHub Enterprise Server 3.8 ou posterior, use os seguintes sinalizadores:
gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME --ghes-api-url GHES-API-URL
gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME --ghes-api-url GHES-API-URL
Se você estiver migrando do GitHub Enterprise Server 3.7 ou anterior e usando o Armazenamento de Blobs do Azure como o provedor de armazenamento de blobs, use os seguintes sinalizadores para se autenticar:
gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME \ --ghes-api-url GHES-API-URL --azure-storage-connection-string "AZURE_STORAGE_CONNECTION_STRING"
gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME \
--ghes-api-url GHES-API-URL --azure-storage-connection-string "AZURE_STORAGE_CONNECTION_STRING"
Se você estiver migrando do GitHub Enterprise Server 3.7 ou anterior e usando o Amazon S3 como o provedor de armazenamento de blobs, use os seguintes sinalizadores para se autenticar:
gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME \ --ghes-api-url GHES-API-URL --aws-bucket-name "AWS-BUCKET-NAME"
gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME \
--ghes-api-url GHES-API-URL --aws-bucket-name "AWS-BUCKET-NAME"
Espaços reservados
Substitua os espaços reservados no comando acima pelos valores a seguir.
Espaço reservado | Valor |
---|---|
SOURCE | Nome da organização de origem |
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 |
GHES-API-URL | A URL para a API do sua instância do GitHub Enterprise Server, como https:/ |
AZURE_STORAGE_CONNECTION_STRING | A cadeia de conexão da sua conta de armazenamento do Azure. Coloque a cadeia de conexão entre aspas, que contém caracteres que provavelmente serão interpretados de outro modo pelo shell. |
AWS-BUCKET-NAME | O nome do bucket da AWS S3 |
Argumentos adicionais
Argument | Descrição |
---|---|
--target-api-url TARGET-API-URL | Se você estiver migrando para o GHE.com, adicione --target-api-url TARGET-API-URL , em que TARGET-API-URL é a URL da API base para o subdomínio da sua empresa. Por exemplo: https:/ . |
--no-ssl-verify | Se o sua instância do GitHub Enterprise Server usar um certificado SSL autoassinado ou inválido, use o sinalizador --no-ssl-verify . Com esse sinalizador, a GitHub CLI vai ignorar a verificação do certificado SSL ao extrair os dados somente da instância. Todas as outras chamadas verificarão o SSL. |
--skip-releases | Se o repositório tiver mais de 10 GB de dados de versões, as versões não poderão ser migradas. Use o sinalizador --skip-releases para migrar o repositório sem versões. |
--target-repo-visibility TARGET-VISIBILITY | Todos os repositórios são migrados com visibilidade privada por padrão. Para definir a visibilidade, você pode adicionar o sinalizador --target-repo-visibility especificando private , public ou internal . Se você estiver migrando para um empresa com usuários gerenciados, os repositórios públicos não estarão disponíveis. |
Como anular a migração
Se você quiser cancelar uma migração, use o comando abort-migration
, substituindo MIGRATION-ID pelo ID retornado de migrate-repo
.
gh gei abort-migration --migration-id MIGRATION-ID
gh gei abort-migration --migration-id MIGRATION-ID
Etapa 7: 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 saber mais, 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.
Após a conclusão da migração, recomendamos excluir os arquivos do contêiner de armazenamento. Se você pretende concluir migrações adicionais, exclua o arquivo colocado no seu contêiner de armazenamento pela ADO2GH extension. Quando terminar a migração, você poderá excluir todo o contêiner.