Como migrar repositórios do GitHub Enterprise Server para o GitHub Enterprise Cloud

Se você optar por usar a API, precisará escrever seus scripts ou usar um cliente HTTP como o Insomnia. Você pode saber mais sobre como começar a usar as APIs de GitHub em Introdução à API REST e Realizar chamadas com o GraphQL.

Para migrar seus repositórios de GitHub Enterprise Server para GitHub Enterprise Cloud com as APIs, você irá:

1. Criar um personal access token para a organização de origem e de destino
2. Recupere o ownerId da organização de destino em GitHub Enterprise Cloud
3. Configure uma origem de migração via API GraphQL de GitHub para identificar de onde você está migrando
4. Para cada repositório que você deseja migrar, repita essas etapas.
   • Use a API sua instância do GitHub Enterprise Server REST para gerar arquivos de migração para seu repositório
   • Carregar seus arquivos de migração para um local onde eles podem ser acessados por GitHub
   • Inicie sua migração usando a API do GraphQL para o destino de migração, transmitindo as URLs de arquivo
   • Verificar o status da migração por meio da API do GraphQL
   • Validar a migração e verificar o log de erros

Para ver instruções para usar os dados da GitHub CLI, use o alternador de ferramentas na parte superior da página.

Etapa 1. Crie seu personal access token

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 saber mais, confira Gerenciando o acesso para uma migração entre produtos GitHub.
2. 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.

Etapa 2: Obter a ownerId da organização de destino

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
  }
}

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 3: Configurar o armazenamento de blobs

Ao executar uma migração de repositório, você deve armazenar os dados do repositório em um local que GitHub Enterprise Importer possa acessar. Isso pode ser feito assim:

• Usando um armazenamento local na instância do GHES (GHES 3.16 e posterior)
• Usando um provedor de armazenamento de blobs

Usar armazenamento local (GHES 3.16+)

Quando você executa uma migração com armazenamento local, os dados de arquivo morto são gravados no disco no sua instância do GitHub Enterprise Server, sem a necessidade de um provedor de armazenamento em nuvem.

• Se você não tiver regras de firewall bloqueando o tráfego de saída de GitHub Enterprise Server, o GitHub Enterprise Importer poderá recuperar automaticamente o arquivo armazenado do GitHub Enterprise Server.
• Se você tiver regras de firewall em vigor e não quiser permitir o acesso a GitHub Enterprise Importer, poderá carregar seus dados de arquivo morto em GitHub-owned blob storage para GitHub Enterprise Importer para acessar. Para fazer isso manualmente, confira Carregar seus arquivos de migração para o armazenamento de blobs de propriedade do GitHub na versão da API deste artigo.

1. Em uma conta administrativa no GitHub Enterprise Server, no canto superior direito de qualquer página, clique em .
2. Na barra lateral " Site admin", clique em Console de Gerenciamento.
3. Entre no Console de Gerenciamento.
4. Na barra lateral à esquerda, clique em Migrações.
5. Clique em Habilitar as Migrações do GitHub.
6. Em "Armazenamento de Migrações", clique em Armazenamento Local.
7. Clique em Salvar alterações.

Ao executar a migração, monitore o espaço em disco no GitHub Enterprise Server. Os arquivos de migração são excluídos automaticamente após sete dias. Para liberar espaço, você pode excluir um arquivo morto usando o Endpoints da API REST para migrações de organizações.

Usando um provedor de armazenamento de blobs

Se sua GitHub Enterprise Server instância estiver atrás de um firewall, talvez seja necessário configurar o armazenamento de blobs com um serviço de nuvem externo.

Primeiro, você precisa configurar o armazenamento de blobs com um provedor compatível. Em seguida, se você estiver usando um provedor de nuvem, deverá configurar suas credenciais para o provedor de armazenamento no Console de Gerenciamento ou GitHub CLI.

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/*"
            ]
        }
    ]
}

Configurar uma conta de 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.

Configurando o armazenamento de blobs no Console de Gerenciamento de sua instância do GitHub Enterprise Server

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.

1. Em uma conta administrativa no GitHub Enterprise Server, no canto superior direito de qualquer página, clique em .

2. 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 " Site admin", clique em Console de Gerenciamento.

3. Faça logon no Console de Gerenciamento.

4. Na barra de navegação superior, clique em Configurações.

5. Em Migrações, clique em Habilitar as Migrações do GitHub .

6. 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.

   Observação

   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.

7. 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.

   Observação

   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, como bucket.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.

8. Clique em Testar configurações de armazenamento.

9. Clique em Salvar alterações.

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 4: Configurar uma fonte de migração no GitHub Enterprise Cloud

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 em GitHub Enterprise Server.

createMigrationSource mutação

mutation createMigrationSource($name: String!, $url: String!, $ownerId: ID!) {
  createMigrationSource(input: {name: $name, url: $url, ownerId: $ownerId, type: GITHUB_ARCHIVE}) {
    migrationSource {
      id
      name
      url
      type
    }
  }
}

| url | O URL para sua instância do GitHub Enterprise Server. Essa URL não precisa ser acessível de GitHub Enterprise Cloud.

createMigrationSource resposta

{
  "data": {
    "createMigrationSource": {
      "migrationSource": {
        "id": "MS_kgDaACRjZTY5NGQ1OC1mNDkyLTQ2NjgtOGE1NS00MGUxYTdlZmQwNWQ",
        "name": "GHES Source",
        "url": "https://my-ghes-hostname.com",
        "type": "GITHUB_ARCHIVE"
      }
    }
  }
}

Neste exemplo, MS_kgDaACRjZTY5NGQ1OC1mNDkyLTQ2NjgtOGE1NS00MGUxYTdlZmQwNWQ é a ID de origem da migração, que usaremos em uma etapa posterior.

Etapa 5: Gerar arquivos de migração em sua instância do GitHub Enterprise Server

Você usará a API REST para iniciar duas "migrações" em GitHub Enterprise Server: uma para gerar um arquivo do código-fonte Git do seu repositório e outra para gerar um arquivo dos metadados do seu repositório (como issues e pull requests).

Para gerar o arquivo de origem do Git, faça uma POST solicitação para https://HOSTNAME/api/v3/orgs/ORGANIZATION/migrations, substituindo HOSTNAME pelo nome do sua instância do GitHub Enterprise Serverhost e ORGANIZATION pelo logon da sua organização.

No corpo, especifique o repositório individual que deseja migrar. A solicitação será parecida com esta:

POST /api/v3/orgs/acme-corp/migrations HTTP/1.1
Accept: application/vnd.github+json
Authorization: Bearer <TOKEN>
Content-Type: application/json
Host: github.acmecorp.net

{
  "repositories": ["repository_to_migrate"],
  "exclude_metadata": true
}

Para gerar o arquivo de metadados, envie uma solicitação semelhante para a mesma URL com o seguinte corpo:

{
  "repositories": ["repository_to_migrate"],
  "exclude_git_data": true,
  "exclude_releases": false,
  "exclude_owner_projects": true
}

Cada uma dessas duas chamadas à API retornará uma resposta JSON, incluindo a ID da migração iniciada.

HTTP/1.1 201 Created

{
  "id": 123,
  // ...
}

Para obter mais informações, confira Iniciar uma migração de organização.

A geração dos arquivos pode demorar um pouco, dependendo do volume de dados. Verifique regularmente o status das migrações com a API "Obter um status de migração da organização" até que o state da migração mude para exported.

GET /api/v3/orgs/acme-corp/migrations/123 HTTP/1.1
Accept: application/vnd.github+json
Authorization: Bearer <TOKEN>
Host: github.acmecorp.net

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 123,
  "state": "exported",
  // ...
}

Para obter mais informações, confira Obter um status de migração da organização.

Depois que o state de uma migração passar para exported, busque a URL da migração usando a API "Baixar um arquivo de migração da organização".

GET /api/v3/orgs/acme-corp/migrations/123/archive HTTP/1.1
Accept: application/vnd.github+json
Authorization: Bearer <TOKEN>
Host: github.acmecorp.net

HTTP/1.1 302 Found
Location: https://media.github.acmecorp.net/migrations/123/archive/cca2ebe9-7403-4ffa-9b6a-4c9e16c94410?token=AAAAABEWE7JP4H2HACKEGMTDOYRC6

A API retornará uma resposta 302 Found com um cabeçalho Location redirecionando você para a URL em que o arquivo para download está localizado. Baixe os dois arquivos: um para a origem do Git e o outro para os metadados.

Para obter mais informações, confira Baixar um arquivo de migração da organização.

Depois que as duas migrações forem concluídas e você baixar os arquivos, vá para a próxima etapa.

Etapa 6: Carregar os arquivos de migração

Para importar seus dados para GitHub Enterprise Cloud, você deve enviar ambos os arquivos de cada repositório (código-fonte Git e metadados) do seu computador para GitHub, usando nossa API GraphQL.

Se você estiver usando GitHub Enterprise Server 3,7 ou inferior, deverá primeiro gerar URLs para os arquivos acessíveis por GitHub. A maioria dos clientes opta por carregar os arquivos no serviço de armazenamento de blobs de um provedor de nuvem, como a Amazon S3 ou o Armazenamento de Blobs do Azure e, em seguida, gerar uma URL de curta duração para cada um.

Se você estiver usando GitHub Enterprise Server 3.8 ou superior, sua instância carregará os arquivos e gerará as URLs para você. O cabeçalho Location da etapa anterior retornará a URL de curta duração.

Talvez seja necessário adicionar os intervalos de IP de GitHub à lista de permissões. Para saber mais, confira Gerenciando o acesso para uma migração entre produtos GitHub.

Carregando seus arquivos de migração para GitHub-owned blob storage

Se você estiver usando GitHub-owned blob storage, fará upload do seu arquivo para GitHub-owned blob storage seguindo o processo abaixo:

1. Criar um upload de várias partes enviando uma solicitação POST
2. Carregar arquivo morto em várias partes com até 100 MB como solicitações PATCH
3. Enviar uma solicitação PUT para concluir o upload

1. Criar o upload de várias partes

Você enviará uma solicitação POST para:

https://uploads.github.com/organizations/{organization_id}/gei/archive/blobs/uploads

Inclua um corpo JSON como abaixo com o nome e o tamanho do arquivo morto. O tipo de conteúdo pode permanecer como "application/octet-stream" para todos os uploads.

{
"content_type": "application/octet-stream",
"name": "git-archive.tar.gz",
"size": 262144000
}

Isso retornará uma resposta de objeto JSON da seguinte maneira:

{
  "guid": "363b2659-b8a3-4878-bfff-eed4bcb54d35",
  "node_id": "MA_kgDaACQzNjNiMjY1OS1iOGEzLTQ4NzgtYmZmZi1lZWQ0YmNiNTRkMzU",
  "name": "git-archive.tar.gz",
  "size": 33287,
  "uri": "gei://archive/363b2659-b8a3-4878-bfff-eed4bcb54d35",
  "created_at": "2024-11-13T12:35:45.761-08:00"
}

Esse URI representa o arquivo morto carregado e será usado para enfileirar a migração quando você iniciar a migração do repositório. A resposta incluirá também o local no cabeçalho de resposta usado para carregar partes de arquivo usando uma solicitação PATCH na próxima etapa:

/organizations/{organization_id}/gei/archive/blobs/uploads?part_number=1&guid=<guid>&upload_id=<upload_id>

2. Carregar o arquivo morto em várias partes

Carregue até 100 MB do arquivo em cada parte com uma solicitação PATCH usando o local do cabeçalho de resposta anterior, garantindo que os dados brutos sejam carregados no corpo da solicitação sem usar um formulário de várias partes. Se a parte final do arquivo for menor que 100 MB, carregue somente os bytes restantes nessa última solicitação:

https://uploads.github.com/{location}

Isso retornará um corpo de resposta vazio com o seguinte local no cabeçalho da resposta:

/organizations/{organization_id}/gei/archive/blobs/uploads?part_number=2&guid=<guid>&upload_id=<upload_id>

Repita isso até que o carregamento seja concluído. Verifique se você está lendo até 100 MB do arquivo por vez e enviando solicitações para os novos valores de local com os valores part_number incrementados.

3. Conclua o upload

Envie uma solicitação PUT para o valor "último caminho" da etapa anterior com um corpo vazio, e o upload para o armazenamento de propriedade do GitHub está concluído. O URI do GEI pode ser criado com o GUID dessa solicitação POST inicial no seguinte formato:

gei://archive/{guid}

Etapa 7: 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.

startRepositoryMigration mutação

mutation startRepositoryMigration (
  $sourceId: ID!,
  $ownerId: ID!,
  $repositoryName: String!,
  $continueOnError: Boolean!,
  $accessToken: String!,
  $githubPat: String!,
  $gitArchiveUrl: String!,
  $metadataArchiveUrl: String!,
  $sourceRepositoryUrl: URI!,
  $targetRepoVisibility: String!
){
  startRepositoryMigration( input: {
    sourceId: $sourceId,
    ownerId: $ownerId,
    repositoryName: $repositoryName,
    continueOnError: $continueOnError,
    accessToken: $accessToken,
    githubPat: $githubPat,
    targetRepoVisibility: $targetRepoVisibility
    gitArchiveUrl: $gitArchiveUrl,
    metadataArchiveUrl: $metadataArchiveUrl,
    sourceRepositoryUrl: $sourceRepositoryUrl,
  }) {
    repositoryMigration {
      id
      migrationSource {
        id
        name
        type
      }
      sourceUrl
    }
  }
}

gitArchiveUrl | Uma URL GitHub Enterprise Cloud acessível para seu arquivo-fonte Git.

metadataArchiveUrl | Uma URL acessível por GitHub Enterprise Cloud para o seu arquivo de metadados.

sourceRepositoryUrl | O endereço URL do seu repositório na sua instância de GitHub Enterprise Server. Isso é necessário, mas GitHub Enterprise Cloud não se comunicará diretamente com sua GitHub Enterprise Server instância.

Para ver os requisitos, consulte Gerenciando o acesso para uma migração entre produtos GitHub.

Na próxima etapa, você usará a ID de migração retornada da mutação startRepositoryMigration para verificar o status da migração.

Etapa 8: 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
    }
  }
}

Etapa 9: 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.