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.
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 Azure DevOps 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 migrações do Azure DevOps 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, você precisa ser um proprietário da organização ou ter a função de migrador. Para obter mais informações sobre a função de migrador, confira "Gerenciando o acesso para uma migração do Azure DevOps".
Etapa 0: Preparar-se para usar a API do GraphQL do GitHub
Para fazer consultas do GraphQL, você precisará escrever seus scripts ou usar um cliente HTTP como o Insomnia.
Para saber mais sobre como começar a usar a API do GraphQL do GitHub, incluindo como se autenticar, confira "Realizar chamadas com o GraphQL".
Etapa 1: Obter a ownerId do destino de migração
Como proprietário de uma organização no GitHub Enterprise Cloud, use a consulta GetOrgInfo para retornar a ownerId, também chamada de ID da organização, na organização da qual você deseja ser proprietário dos repositórios migrados. Você precisará da ownerId para identificar seu destino de migração.
Consulta GetOrgInfo
query(
$login: String!
){
organization (login: $login)
{
login
id
name
databaseId
}
}
| Variável da consulta | Descrição |
|---|---|
login | O nome da sua organização. |
Resposta GetOrgInfo
{
"data": {
"organization": {
"login": "Octo",
"id": "MDEyOk9yZ2FuaXphdGlvbjU2MTA=",
"name": "Octo-org",
"databaseId": 5610
}
}
}
Neste exemplo, MDEyOk9yZ2FuaXphdGlvbjU2MTA= é a ID da organização ou ownerId, que usaremos na próxima etapa.
Etapa 2: Identificar a origem da migração
Você pode configurar uma origem de migração usando a consulta createMigrationSource. Você precisará fornecer a ownerId, ou a ID da organização, coletada da consulta GetOrgInfo.
Sua fonte de migração é sua organização do ADO.
Mutação createMigrationSource
mutation createMigrationSource($name: String!, $ownerId: ID!) {
createMigrationSource(input: {name: $name, url: "https://dev.azure.com", ownerId: $ownerId, type: AZURE_DEVOPS}) {
migrationSource {
id
name
url
type
}
}
}
Observação: use AZURE_DEVOPS para type.
| Variável da consulta | Descrição |
|---|---|
name | Um nome para a origem da migração. Esse nome se destina à sua referência, ou seja, você pode usar qualquer cadeia de caracteres. |
ownerId | A ID da sua organização no GitHub Enterprise Cloud. |
Resposta createMigrationSource
{
"data": {
"createMigrationSource": {
"migrationSource": {
"id": "MS_kgDaACQxYmYxOWU4Yi0wNzZmLTQ3NTMtOTdkZC1hNGUzZmYxN2U2YzA",
"name": "Azure Devops Source",
"url": "https://dev.azure.com",
"type": "AZURE_DEVOPS"
}
}
}
}
Neste exemplo, MS_kgDaACQxYmYxOWU4Yi0wNzZmLTQ3NTMtOTdkZC1hNGUzZmYxN2U2YzA é a ID de origem de migração, que usaremos na próxima etapa.
Etapa 3: Iniciar a migração do repositório
Quando você inicia uma migração, um repositório individual e os dados complementares são migrados para um novo repositório do GitHub identificado por você.
Caso você deseje mover vários repositórios ao mesmo tempo da mesma organização de origem, coloque várias migrações na fila. É possível executar até cinco migrações de repositório ao mesmo tempo.
Mutação startRepositoryMigration
mutation startRepositoryMigration (
$sourceId: ID!,
$ownerId: ID!,
$sourceRepositoryUrl: URI!,
$repositoryName: String!,
$continueOnError: Boolean!,
$accessToken: String!,
$githubPat: String!,
$targetRepoVisibility: String!
){
startRepositoryMigration( input: {
sourceId: $sourceId,
ownerId: $ownerId,
repositoryName: $repositoryName,
continueOnError: $continueOnError,
accessToken: $accessToken,
githubPat: $githubPat,
targetRepoVisibility: $targetRepoVisibility
sourceRepositoryUrl: $sourceRepositoryUrl,
}) {
repositoryMigration {
id
migrationSource {
id
name
type
}
sourceUrl
}
}
}
| Variável da consulta | Descrição |
|---|---|
sourceId | A origem de migração id retornou da mutação createMigrationSource. |
ownerId | A ID da sua organização no GitHub Enterprise Cloud. |
repositoryName | Um nome de repositório exclusivo personalizado não usado atualmente por nenhum dos seus repositórios pertencentes à organização no GitHub Enterprise Cloud. Um problema de log de erros será criado neste repositório quando a migração for concluída ou tiver sido interrompida. |
continueOnError | Configuração de migração que permite que a migração continue ao encontrar erros que não causam falha na migração. Deve ser true ou false. Recomendamos fortemente definir continueOnError como true, de modo que a migração continue, a menos que o Importer não possa mover a origem do Git ou o Importer tenha perdido a conexão e não possa se reconectar para concluir a migração. |
githubPat | O personal access token da sua organização de destino no GitHub Enterprise Cloud. |
accessToken | Os dados do personal access token da origem. |
targetRepoVisibility | A visibilidade do novo repositório. Deve ser private, public ou internal. Se isso não estiver definido, seu repositório será migrado como privado. |
sourceRepositoryUrl | A URL do repositório de origem, usando o formato https://dev.azure.com/{organization}/{project}/_git/{repository}. |
Para ver os requisitos do personal access token, confira "Gerenciando o acesso para uma migração do Azure DevOps".
Na próxima etapa, você usará a ID de migração retornada da mutação startRepositoryMigration para verificar o status da migração.
Etapa 4: Verificar o status da migração
Para detectar qualquer falha de migração e garantir que a migração esteja funcionando, verifique o status da migração usando a consulta getMigration. Você também pode verificar o status de várias migrações com getMigrations.
A consulta getMigration retornará com um status para informar se a migração é queued, in progress, failed ou completed. Em caso de falha na migração, o Importer fornecerá um motivo para a falha.
Consulta getMigration
query (
$id: ID!
){
node( id: $id ) {
... on Migration {
id
sourceUrl
migrationSource {
name
}
state
failureReason
}
}
}
| Variável da consulta | Descrição |
|---|---|
id | A id da migração que a mutação startRepositoryMigration retornou. |
Etapa 5: Validar a migração e verificar o log de erros
Para concluir a migração, recomendamos que você verifique o problema "Log de Migração". Esse problema é criado no GitHub no repositório de destino.
Por fim, recomendamos que você revise os repositórios migrados para uma verificação de integridade.
Etapa 1: instalar o ADO2GH extension of the GitHub CLI
Se essa for sua primeira migração, você precisará instalar o ADO2GH extension of the GitHub CLI. Para obter mais informações sobre o 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-ado2gh. 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.
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. -
Instalar o ADO2GH extension.
Shell gh extension install github/gh-ado2gh
gh extension install github/gh-ado2gh
Sempre que precisar de ajuda com a ADO2GH extension, use o sinalizador --help com um comando. Por exemplo, gh ado2gh --help listará todos os comandos disponíveis, e gh ado2gh migrate-repo --help listará todas as opções disponíveis para o comando migrate-repo.
Etapa 2: atualizar o ADO2GH extension of the GitHub CLI
O ADO2GH extension of the GitHub CLI é atualizado semanalmente. Para garantir que você esteja usando a última versão, atualize a extensão.
gh extension upgrade github/gh-ado2gh
gh extension upgrade github/gh-ado2gh
Etapa 3: Definir variáveis de ambiente
Para usar o ADO2GH extension para migrar para o GitHub Enterprise Cloud, você precisará 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 obter mais informações, confira "Gerenciando o acesso para uma migração do Azure DevOps".
-
Crie e registre um personal access token que será autenticado para a organização de origem no Azure DevOps, verificando se esse token atende a todos os requisitos. Para obter mais informações, confira "Gerenciando o acesso para uma migração do Azure DevOps".
-
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_PATpara a organização de destino eADO_PATpara a organização de origem.-
Se você estiver usando o Terminal, use o comando
export.Shell export GH_PAT="TOKEN" export ADO_PAT="TOKEN"
export GH_PAT="TOKEN" export ADO_PAT="TOKEN" -
Se você estiver usando o PowerShell, use o comando
$env.Shell $env:GH_PAT="TOKEN" $env:ADO_PAT="TOKEN"
$env:GH_PAT="TOKEN" $env:ADO_PAT="TOKEN"
-
Etapa 4: 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.
Observação: a geração de 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
Para gerar um script de migração, execute o comando gh ado2gh generate-script.
gh ado2gh generate-script --ado-org SOURCE --github-org DESTINATION --output FILENAME
gh ado2gh generate-script --ado-org SOURCE --github-org DESTINATION --output FILENAME
Para adicionar funcionalidades adicionais ao script, como rewiring de pipelines, criação de equipes e configuração de integrações de Azure Boards, você poderá adicionar o sinalizador --all.
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 |
|---|---|
| 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. |
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-repocorrespondente. - Se você quiser alterar a visibilidade do novo repositório, atualize o valor do sinalizador
--target-repo-visibilitycorrespondente. Por padrão, o script define a mesma visibilidade que o repositório de origem.
Se você baixou ADO2GH 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 ado2gh.
Etapa 5: 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 ado2gh migrate-repo.
Migrar vários repositórios
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
Para migrar um repositório individual, use o comando gh ado2gh migrate-repo.
gh ado2gh migrate-repo --ado-org SOURCE --ado-team-project TEAM-PROJECT --ado-repo CURRENT-NAME --github-org DESTINATION --github-repo NEW-NAME
gh ado2gh migrate-repo --ado-org SOURCE --ado-team-project TEAM-PROJECT --ado-repo CURRENT-NAME --github-org DESTINATION --github-repo NEW-NAME
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 |
| TEAM-PROJECT | Nome do projeto de equipe do repositório que você deseja migrar |
Se você quiser cancelar uma migração, use o comando abort-migration, substituindo MIGRATION-ID pelo ID retornado de migrate-repo.
gh ado2gh abort-migration --migration-id MIGRATION-ID
gh ado2gh 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.