Sobre migrações entre empresas com residência de dados
As migrações entre duas empresas com residência de dados usam o fluxo padrão de migração do arquivo GEI:
- O GEI conecta-se ao subdomínio de origem GHE.com .
- O GEI gera um arquivo compactado contendo os dados do repositório.
- O GEI faz upload do arquivo para o armazenamento de migração compatível.
- O GEI inicia a migração do repositório no subdomínio de destino GHE.com .
- O destino Importer baixa e processa o arquivo.
Nesta migração:
- A origem é um GHE.com subdomínio, como
https://SOURCE_SUBDOMAIN.ghe.com. - O destino é um subdomínio diferente GHE.com , como
https://DESTINATION_SUBDOMAIN.ghe.com. - As organizações de origem e de destino podem ter nomes diferentes.
- O repositório migrado pode ter um nome diferente na organização de destino.
Os pontos de extremidade da API de origem e de destino devem ser especificados independentemente. Não use a URL da API de destino para operações de origem.
Importante
GitHub Enterprise Cloud com residência de dados As URLs de API usam o formato https://api.SUBDOMAIN.ghe.com. Isso é diferente de uma GitHub Enterprise Server URL de API, que normalmente usa o formato https://HOSTNAME/api/v3.
Pré-requisitos
Antes de começar:
- Confirme se a origem e o destino são subdomínios diferentes GHE.com .
- Nas organizações de origem e de destino, verifique se você é um proprietário da organização ou recebeu a função de migrador.
- Crie um personal access token (classic) para a organização de origem.
- Crie um personal access token (classic) para a organização de destino. Para escopos necessários, consulte Gerenciando o acesso para uma migração entre produtos GitHub.
- Execute uma migração de avaliação antes de executar a migração de produção.
Recomendamos interromper temporariamente o trabalho no repositório de origem durante a migração de produção. GitHub Enterprise Importer não executa migrações delta, portanto, as alterações feitas após o início da migração não são incluídas automaticamente.
Para obter informações sobre os dados migrados e as limitações conhecidas, consulte Sobre migrações entre produtos do GitHub com GitHub Enterprise Importer.
Instalar o GitHub CLI e o GEI
Instale o GitHub CLI e, em seguida, instale a extensão GEI:
gh extension install github/gh-gei
gh extension install github/gh-gei
Atualize a extensão antes de iniciar uma migração:
gh extension upgrade github/gh-gei
gh extension upgrade github/gh-gei
Para exibir as opções disponíveis:
gh gei migrate-repo --help
gh gei migrate-repo --help
Definir variáveis de ambiente
Defina os personal access tokens para ambas as empresas:
export GH_SOURCE_PAT="SOURCE_PERSONAL_ACCESS_TOKEN" export GH_PAT="DESTINATION_PERSONAL_ACCESS_TOKEN"
export GH_SOURCE_PAT="SOURCE_PERSONAL_ACCESS_TOKEN"
export GH_PAT="DESTINATION_PERSONAL_ACCESS_TOKEN"
Defina a URL da API para cada GHE.com subdomínio:
export SOURCE_API_URL="https://api.SOURCE_SUBDOMAIN.ghe.com" export TARGET_API_URL="https://api.DESTINATION_SUBDOMAIN.ghe.com"
export SOURCE_API_URL="https://api.SOURCE_SUBDOMAIN.ghe.com"
export TARGET_API_URL="https://api.DESTINATION_SUBDOMAIN.ghe.com"
Substitua SOURCE_SUBDOMAIN e DESTINATION_SUBDOMAIN pelos subdomínios de sua empresa de origem e destino.
Por exemplo:
export SOURCE_API_URL="https://api.source-example.ghe.com" export TARGET_API_URL="https://api.destination-example.ghe.com"
export SOURCE_API_URL="https://api.source-example.ghe.com"
export TARGET_API_URL="https://api.destination-example.ghe.com"
O GH_SOURCE_PAT token é usado para operações do lado da origem, incluindo a geração de arquivos. O GH_PAT token é usado para operações do lado do destino.
Configurar o armazenamento de blobs de arquivos
GitHub Enterprise Importer exporta cada projeto para um arquivo e, em seguida, envia o arquivo para o armazenamento de blobs, do qual GitHub pode ler. Você escolhe o back-end de armazenamento ao executar uma migração:
| Opção de armazenamento | Como selecioná-lo | Notes |
|---|
GitHub-owned blob storage (recomendado) | --use-github-storage | Nenhuma configuração é necessária.
GitHub exclui o arquivo automaticamente após uma migração bem-sucedida ou após sete dias de uma migração com falha.
AWS S3 |
--aws-bucket-name (com as variáveis de ambiente AWS_REGION, AWS_ACCESS_KEY_ID e AWS_SECRET_ACCESS_KEY, e opcionalmente AWS_SESSION_TOKEN) | Você é responsável pelo bucket e por seu ciclo de vida.
GitHub não exclui arquivos do armazenamento.
Armazenamento de Blobs do Azure |
AZURE_STORAGE_CONNECTION_STRING variável de ambiente (para um único migrate-repo comando, você pode usar --azure-storage-connection-string) | Há suporte apenas para cadeias de conexão de chave de acesso de conta de armazenamento (não SAS).
GitHub não exclui arquivos do armazenamento.
Migrar um repositório individual
Para migrar um único repositório, use o gh gei migrate-repo comando:
gh gei migrate-repo \ --github-source-org SOURCE_ORGANIZATION \ --source-repo SOURCE_REPOSITORY \ --github-source-api-url "$SOURCE_API_URL" \ --github-target-org DESTINATION_ORGANIZATION \ --target-repo DESTINATION_REPOSITORY \ --target-api-url "$TARGET_API_URL" \ --verbose
gh gei migrate-repo \
--github-source-org SOURCE_ORGANIZATION \
--source-repo SOURCE_REPOSITORY \
--github-source-api-url "$SOURCE_API_URL" \
--github-target-org DESTINATION_ORGANIZATION \
--target-repo DESTINATION_REPOSITORY \
--target-api-url "$TARGET_API_URL" \
--verbose
Substitua os marcadores pelos seguintes valores:
| Espaço reservado | Description |
|---|---|
SOURCE_ORGANIZATION | A organização que possui o repositório na empresa de origem. |
SOURCE_REPOSITORY | O nome do repositório na organização de origem. |
DESTINATION_ORGANIZATION | A organização que será dona do repositório migrado na empresa de destino. |
DESTINATION_REPOSITORY | O nome do novo repositório na organização de destino. |
Por exemplo:
gh gei migrate-repo \ --github-source-org source-org \ --source-repo example-repository \ --github-source-api-url "$SOURCE_API_URL" \ --github-target-org destination-org \ --target-repo example-repository \ --target-api-url "$TARGET_API_URL" \ --verbose
gh gei migrate-repo \
--github-source-org source-org \
--source-repo example-repository \
--github-source-api-url "$SOURCE_API_URL" \
--github-target-org destination-org \
--target-repo example-repository \
--target-api-url "$TARGET_API_URL" \
--verbose
Se você omitir --target-repo, GEI usará o nome do repositório de origem.
Argumentos opcionais
Você pode adicionar as seguintes opções ao comando de migração:
| Argument | Description |
|---|---|
--target-repo-visibility TARGET-VISIBILITY | Define a visibilidade do novo repositório. Os valores com suporte são private e internal. |
--skip-releases | Migra o repositório sem releases. |
--queue-only | Enfileira a migração sem esperar que seja concluída. |
--verbose | Exibe saída de migração adicional. |
Por exemplo:
gh gei migrate-repo \ --github-source-org source-org \ --source-repo example-repository \ --github-source-api-url "$SOURCE_API_URL" \ --github-target-org destination-org \ --target-repo example-repository \ --target-api-url "$TARGET_API_URL" \ --target-repo-visibility internal \ --verbose
gh gei migrate-repo \
--github-source-org source-org \
--source-repo example-repository \
--github-source-api-url "$SOURCE_API_URL" \
--github-target-org destination-org \
--target-repo example-repository \
--target-api-url "$TARGET_API_URL" \
--target-repo-visibility internal \
--verbose
Migrar vários repositórios
Para vários repositórios, use gh gei generate-script.
gh gei generate-script \ --github-source-org SOURCE_ORGANIZATION \ --github-target-org DESTINATION_ORGANIZATION \ --github-source-api-url "$SOURCE_API_URL" \ --target-api-url "$TARGET_API_URL" \ --output migration-script.ps1
gh gei generate-script \
--github-source-org SOURCE_ORGANIZATION \
--github-target-org DESTINATION_ORGANIZATION \
--github-source-api-url "$SOURCE_API_URL" \
--target-api-url "$TARGET_API_URL" \
--output migration-script.ps1
Examine o script gerado antes de executá-lo. É possível:
- Remova repositórios que não devem ser migrados.
- Altere os nomes do repositório de destino.
- Alterar a visibilidade do repositório de destino.
- Adicionar opções como
--skip-releases. - Adicione
--download-migration-logsaos logs de download para cada migração.
Execute o script gerado com o PowerShell:
pwsh ./migration-script.ps1
pwsh ./migration-script.ps1
Verificar o status de uma migração
Se você iniciou a migração com --queue-only, use a ID de migração impressa pela GEI para monitorá-la:
gh gei wait-for-migration \ --migration-id MIGRATION_ID \ --target-api-url "$TARGET_API_URL" \ --verbose
gh gei wait-for-migration \
--migration-id MIGRATION_ID \
--target-api-url "$TARGET_API_URL" \
--verbose
Substitua MIGRATION_ID pela ID retornada por gh gei migrate-repo.
Observação
Inclua ambos os argumentos de URL da API ao verificar. A URL da API de origem é necessária para comandos GEI que recuperam as informações e logs de migração do lado da origem.
Baixar logs de migração
Para baixar os logs de migração:
gh gei download-logs \ --migration-id MIGRATION_ID \ --github-source-api-url "$SOURCE_API_URL" \ --target-api-url "$TARGET_API_URL"
gh gei download-logs \
--migration-id MIGRATION_ID \
--github-source-api-url "$SOURCE_API_URL" \
--target-api-url "$TARGET_API_URL"
Revise os logs para identificar avisos e erros, mesmo quando a migração indicar sucesso.
Anular uma migração
Para anular uma migração na fila ou em execução:
gh gei abort-migration \ --migration-id MIGRATION_ID \ --github-source-api-url "$SOURCE_API_URL" \ --target-api-url "$TARGET_API_URL"
gh gei abort-migration \
--migration-id MIGRATION_ID \
--github-source-api-url "$SOURCE_API_URL" \
--target-api-url "$TARGET_API_URL"
Solução de problemas
O locatário de origem não pode ser acessado
Verifique se:
--github-source-api-urlé definido como o subdomínio de origem.- A URL usa o formato
https://api.SUBDOMAIN.ghe.com. - O token de origem é armazenado em
GH_SOURCE_PAT. - O token tem acesso à organização e ao repositório de origem.
O locatário de destino não pode ser alcançado
Verifique se:
--target-api-urlé definido como o subdomínio de destino.- A URL usa o formato
https://api.SUBDOMAIN.ghe.com. - O token de destino é armazenado em
GH_PAT. - Você tem permissão para criar repositórios na organização de destino.
A migração falha ao gerar ou enviar o arquivo compactado
Examine o resultado da migração e os logs, depois verifique se:
- O armazenamento de arquivos de migração está configurado corretamente.
- O provedor de armazenamento é acessível ao serviço de migração.
- O repositório de origem não está sendo modificado durante a migração.
- As URLs da API de origem e de destino não foram trocadas.
Os logs não podem ser baixados
Ao usar download-logs, wait-for-migrationou abort-migrationfornecer as mesmas URLs de API de origem e de destino usadas para iniciar a migração:
--github-source-api-url "$SOURCE_API_URL" \
--target-api-url "$TARGET_API_URL"
A URL de origem é rejeitada
Verifique se você está usando o endpoint da API no subdomínio GHE.com em vez de um endpoint GitHub Enterprise Server.
Uso:
https://api.SUBDOMAIN.ghe.com
Não use:
https://HOSTNAME/api/v3
O /api/v3 formato destina-se a GitHub Enterprise Server fontes e não é o formato correto para GitHub Enterprise Cloud com residência de dados.