Migrando seu repositório com Enterprise Live Migrations

Pré-requisitos

Verifique se seus ambientes e desenvolvedores estão prontos para a migração. Consulte Preparando sua migração ao vivo do GitHub Enterprise Server para o GHE.com.

1. Configurar GitHub Enterprise Server

Você deve definir alguma configuração na GitHub Enterprise Server instância antes de criar tokens e executar uma migração. Esses valores de configuração se aplicam a todas as ELM migrações. Os desenvolvedores que utilizam GitHub Enterprise Server podem passar por um breve tempo de inatividade ao aplicar a nova configuração.

1. Acesse o GitHub Enterprise Server shell administrativo por SSH. Consulte Acessar o shell administrativo (SSH).

2. Defina as variáveis de configuração a seguir com ghe-config.

   Por exemplo: ghe-config app.elm-exporter.enabled true

   Variable	Defina isso como...
   app.elm-exporter.enabled	true
   app.elm.internal-webhooks-enabled	true
   app.elm-exporter.webhooks-loopback-address-enabled	true
   secrets.elm-exporter.migration-target-url	A URL da API para sua empresa de destino (por exemplo: https://api.octocorp.ghe.com).

Não inclua uma barra no final da URL. | | secrets.elm-exporter.source-user | O nome de usuário associado ao token GitHub Enterprise Server do operador. Este deve ser o seu nome de usuário em GitHub Enterprise Server; se outra pessoa for criar este token, o valor aqui deverá ser definido como o nome de usuário dessa pessoa. Recomendamos o ghe-admin usuário. |

1. Aplicar a configuração.

   Shell

   ghe-config-apply
   

2. Saia da sessão SSH. Você executará o restante dos comandos em uma sessão de terminal local.

2. Criar tokens de operador com acesso corporativo

O operador deve se autenticar em ambas as empresas, de origem e de destino, com um personal access token (classic). Para obter instruções sobre como criar tokens, consulte Gerenciar seus tokens de acesso pessoal.

Anote ambos os tokens, pois você precisará deles na próxima etapa.

1. Em GitHub Enterprise Server, crie um personal access token (classic) e selecione o escopo exigido:

   • admin:enterprise

   Você usará esse token como o token de origem ao configurar o ELM CLI.

2. Em GHE.com, crie um personal access token (classic) e selecione os escopos exigidos:

   • admin:enterprise
   • admin:org

   Você usará esse token como o token de destino ao configurar o ELM CLI.

3. Configurar a ELM ferramenta de linha de comando

Você executará a migração em uma sessão local do terminal, com uma extensão do GitHub CLI.

1. Instale o GitHub CLI na sua máquina local. Você deve estar usando a versão 2.0 ou posterior.

2. Instale a extensão ELM.

   Shell

   gh extension install github/gh-elm
   

3. Inicie o assistente de instalação para configurar a extensão.

   Shell

   gh elm configure
   

4. Siga as instruções no assistente de instalação, fornecendo as URLs de API (por exemplo: https://api.SUBDOMAIN.ghe.com) para sua origem e destino e os tokens que você criou na etapa anterior.

Qualquer um desses valores também pode ser fornecido como flags de CLI em qualquer comando gh elm, e eles terão prioridade sobre a configuração. Por exemplo: --target-url https://api.SUBDOMAIN.ghe.com.

Esse processo de instalação armazenará as URLs em um arquivo de configuração específico da plataforma no diretório de configuração do sistema operacional.gh-elm/config.json Os tokens de acesso serão armazenados com segurança no armazenamento secreto do seu computador.

4. Configurar as credenciais de migração em tempo real

Além dos tokens de operador com acesso corporativo, você deve criar um personal access token (classic) para as organizações de origem e destino. Você deve repetir essas etapas para cada organização da qual está migrando.

Criar tokens de acesso

ELM deve autenticar com um personal access token (classic) para a origem e o destino da migração. Para obter instruções sobre como criar tokens, consulte Gerenciar seus tokens de acesso pessoal.

Verifique se você anotou esses tokens, pois precisará deles na próxima etapa.

1. Crie um personal access token (classic) em GitHub Enterprise Server com os seguintes escopos:

   • repo
   • admin:org
   • admin:repo_hook
   • admin:org_hook

   Esse é o token de origem.

2. Crie um personal access token (classic) em GHE.com com os seguintes escopos:

   • repo
   • workflow
   • admin:org
   • admin:repo_hook
   • admin:enterprise

   Esse é o token de destino.

   Importante

   Se o logon único for imposto na organização de destino em GHE.com, você deverá autorizar o token GHE.com para SSO.

Configure os ELM segredos da sua organização

Use os gh elm config comandos para definir os tokens de acesso de origem e de destino:

1. Defina o token de origem.

   Shell

   gh elm config set-source-pat EXISTING-GHES-ORG
   

   Cole o token de origem no terminal quando solicitado.

2. Defina o token de destino.

   Shell

   gh elm config set-target-pat EXISTING-GHES-ORG
   

   Cole o token de destino no terminal quando solicitado.

Você também pode definir os tokens interativamente, usando gh elm config org-tokens EXISTING-GHES-ORGou nas configurações da sua organização em https://GHES_HOSTNAME/organizations/EXISTING-GHES-ORG/settings/secrets/elm-exporter/.

5. Criar uma migração

Crie uma nova migração especificando os detalhes do repositório de origem e de destino.

gh elm migration create \
  --source-org EXISTING-GHES-ORG \
  --source-repo EXISTING-GHES-REPO \
  --target-org GHEC-ORG \
  --target-repo NEW-GHEC-REPO

gh elm migration create \
  --source-org EXISTING-GHES-ORG \
  --source-repo EXISTING-GHES-REPO \
  --target-org GHEC-ORG \
  --target-repo NEW-GHEC-REPO

Por exemplo:

gh elm migration create \
  --source-org my-ghes-org \
  --source-repo my-ghes-repo \
  --target-org my-dr-org \
  --target-repo my-dr-repo

Sinalizadores opcionais:

• --start: se você estiver pronto para iniciar a migração imediatamente.
• --target-visibility: repositórios migrados são criados com visibilidade interna por padrão, mas você pode especificar private.

Salvar o ID da migração

Você deverá ver uma resposta semelhante à seguinte:

{
  "migrationId": "2b5c9eae-b5da-4306-ab04-2a29cc2b7cb9",
  "expiresAt": "2026-02-11T21:49:33.619162159Z"
}

Exporte como migrationId uma variável, pois você precisará dela para os próximos comandos. Por exemplo:

export MIGRATION_ID='2b5c9eae-b5da-4306-ab04-2a29cc2b7cb9'

6. Iniciar a migração

Se você ainda não iniciou a migração, inicie-a agora usando a ID de migração que você acabou de salvar.

gh elm migration start --migration-id $MIGRATION_ID

gh elm migration start --migration-id $MIGRATION_ID

Isso inicia os processos de backfill e atualização em tempo real. ELM agora está coletando dados do repositório de origem e monitorando eventos de webhook com suporte.

7. Monitorar a migração

Quando a migração for iniciada, você deverá ver um novo repositório.GHE.com Durante a migração, você verá o preenchimento do repositório com uma carga inicial de dados e receberá atualizações à medida que os desenvolvedores continuarem a trabalhar no repositório de origem.

Você pode monitorar o progresso da migração interativamente usando o watch comando:

gh elm migration watch $MIGRATION_ID

Isso consultará a API de status da migração e exibirá uma interface textual atualizada automaticamente que reflete o progresso atual.

Monitoramento programático usando migration status

Se você quiser um status de migração adequado para automação, use o status comando:

gh elm migration status --migration-id $MIGRATION_ID

gh elm migration status --migration-id $MIGRATION_ID

O indicador mais importante na resposta é o status no objeto combinedState . Quando o status chegar COMBINED_STATUS_READY_FOR_CUTOVER, você deverá estar pronto para prosseguir para a próxima etapa. No entanto, você será alertado no displayMessage se algum recurso individual não tiver migrado, o que talvez seja necessário investigar.

Por exemplo:

  "combinedState":  {
    "status":  "COMBINED_STATUS_READY_FOR_CUTOVER",
    "displayMessage":  "Ready for cutover (1 resources failed)",
    "repositories":  [
      {
        "repositoryNwo":  "new-test-org/my-new-repo",
        "phase":  "REPOSITORY_PHASE_READY_FOR_CUTOVER",
        "displayStatus":  "Ready for cutover (1 failed)"
      }
    ],
    "readyForCutover":  true,
    "cutoverBlockers":  []
  },

Dicas:

• Se você estiver executando várias migrações, poderá verificar o status de todas elas com gh elm migration list. Esse comando mostra migrações em andamento por padrão, mas você também pode filtrar por --status.
• Se você encontrar status de falha que exijam atenção, consulte Solução de problemas de migrações dinâmicas do GitHub Enterprise Server para o GHE.com.

8. Concluir a migração

Quando uma migração estiver pronta para entrada em operação, você pode concluir a migração. O processo de migração arquivará o repositório de origem, fazendo com que ele fique permanentemente em modo somente leitura, a menos que um administrador do repositório o desarquive.

gh elm migration cutover --migration-id $MIGRATION_ID

gh elm migration cutover --migration-id $MIGRATION_ID

Continue monitorando a migração. Quando você vê o MIGRATION_STATUS_COMPLETED status na parte superior da resposta, a migração é concluída, embora haja algumas tarefas de acompanhamento para dar acesso aos usuários de GitHub Enterprise Server.

Próximas Etapas 

Dê aos usuários acesso ao novo repositório e reconcilie a atividade com contas de usuário. Consulte Concluindo sua migração ao vivo do GitHub Enterprise Server para o GHE.com.