Solução de problemas de migração com o GitHub Enterprise Importer

Caso ocorra uma falha na migração ou ela produza resultados inesperados, experimente as etapas comuns de solução de problemas.

Neste artigo

Sobre as etapas de solução de problemas para o GitHub Enterprise Importer

Caso ocorra uma falha na migração ou ela produza resultados inesperados, experimente as primeiras etapas da solução de problemas abaixo, que normalmente resolvem uma variedade de problemas. Se essas primeiras etapas não resolverem o problema, verifique se há mensagens de erro nos logs para a migração. Em seguida, localize a mensagem de erro neste artigo e experimente as etapas de resolução.

Caso não consiga resolver o problema depois de experimentar as etapas de solução de problemas para a mensagem de erro, entre em contato com o Suporte do GitHub.

Primeiras etapas para a solução de problemas

Antes de investigar mais a fundo, experimente estas etapas de solução de problemas que normalmente resolvem uma variedade de problemas.

  1. Verifique se você está usando a última versão da extensão da GitHub CLI usada para a migração. Caso contrário, atualize para a última versão.

  2. Verifique se você atendeu a todos os requisitos de acesso. Para obter mais informações, consulte o artigo apropriado para o caminho de migração.

  3. Tente executar a migração novamente. Alguns problemas de migrações são transitórios. Tentar novamente pode funcionar.

  4. Tente executar uma migração em outros repositórios com os dados semelhantes. Isso ajudará a determinar se o problema é exclusivo do repositório ou se representa um problema de formato de dados mais amplo.

Se essas etapas não resolverem o problema, analise os logs de migração em busca de mensagens de erro. O log que precisará ser verificado varia conforme a falha ou sucesso da migração.

Solução de problemas de falhas em migrações

Em caso de falha na migração, analise as entradas de log detalhadas produzidas pela GitHub CLI de cada migração. O arquivo de log é salvo no mesmo diretório em que você executou a migração.

O log contém um registro de cada comando emitido e todas as solicitações de API que a GitHub CLI fez em resposta. Normalmente, as falhas e as mensagens de erro são exibidas no final do log.

Não é possível executar migrações

Se você observar um erro como No access to createMigrationMutation ou Missing permissions, sua conta pessoal não terá o acesso necessário para executar a migração. Verifique se você é um proprietário da organização ou se recebeu a função de migrador. Para obter mais informações sobre como conceder a função de migrador, confira "Sobre o GitHub Enterprise Importer".

Observação: se você estiver migrando entre produtos do GitHub, verifique se você é um proprietário da organização ou se recebeu a função de migrador para as organizações de origem e de destino.

O recurso é protegido pela imposição do SAML da organização

Esse erro indica que um personal access token fornecido à GitHub CLI precisa ser autorizado para uso com o logon único do SAML. Para obter mais informações, confira "Autorizar o uso de um token de acesso pessoal para uso com logon único SAML".

Resposta 401 Unauthorized

As falhas que incluem o código de status 401 geralmente indicam que o personal access token que você forneceu à GitHub CLI não tem os escopos necessários. Verifique os escopos nos personal access tokens fornecidos. Para obter mais informações sobre escopos necessários, consulte o artigo apropriado para o caminho de migração.

Resposta 404 Not Found

As falhas que incluem o código de status 404 geralmente indicam um erro de digitação em um dos comandos. Analise o log de migração para ver o comando exato inserido e verifique se há erros de digitação no nome do repositório de origem, da organização ou do projeto.

Resposta Archive generation failed

Se você receber uma resposta Archive generation failed... ao migrar do GitHub Enterprise Server, seu repositório provavelmente será muito grande. Para obter mais informações sobre os limites de tamanho do repositório, confira "Sobre migrações entre produtos GitHub".

Primeiro, tente excluir as versões da migração usando o sinalizador --skip-releases com o comando migrate-repo.

Caso isso não funcione, recomendamos atualizar para o GitHub Enterprise Server 3.8.0 ou posterior. Se não for possível atualizá-lo, outra opção será gerar os arquivos do repositório manualmente usando ghe-migrator:

  1. Gere um arquivo de migração para o repositório. Você só deve exportar um repositório por vez. Para obter instruções, confira "Como exportar os dados de migração da sua empresa" na documentação do GitHub Enterprise Server.
  2. Carregue o arquivo de migração para o provedor de armazenamento de blobs escolhido.
  3. Gere uma URL de curta duração para o arquivo de migração que possa ser acessada pelo GitHub.com, como uma URL pré-assinada da AWS S3 ou uma URL SAS do Armazenamento de Blobs do Azure.
  4. Chame o comando migrate-repo com os sinalizadores --git-archive-url e --metadata-archive-url definidos como a URL do arquivo da etapa anterior.

cipher name is not supported erro(s)

Se você estiver migrando do Bitbucket Server e receber um erro como cipher name aes256-ctr for openssh key file is not supported ao executar uma migração, sua chave privada SSH usará uma criptografia sem suporte. Para obter mais informações sobre as criptografias com suporte, confira "Gerenciar o acesso para uma migração do Bitbucket Server".

Para gerar um novo par de chaves SSH compatível, execute o seguinte comando:

Shell
ssh-keygen -t ed25519 -Z aes256-cbc -C "your_email@example.com"

Depois de gerar um novo par de chaves SSH, para usar a chave, você precisa adicionar a chave pública às authorized_keys da instância do Bitbucket Server.

Subsystem 'sftp' could not be executed erro(s)

Se você estiver migrando do Bitbucket Server e receber um erro como Subsystem 'sftp' could not be executed, isso indicará que o SFTP não está habilitado no servidor ou a sua conta de usuário não tem acesso ao SFTP.

Entre em contato com o administrador do servidor e peça para ele habilitar o acesso ao SFTP na sua conta de usuário.

Source export archive... does not exist erro(s)

Se você estiver fazendo a migração do Bitbucket Server e receber um erro como Source export archive (/var/atlassian/application-data/bitbucket/shared/migration/export/Bitbucket_export_1.tar) does not exist, a GitHub CLI estará procurando o arquivo de migração no lugar errado na instância do Bitbucket Server.

Para resolve esse problema, defina o argumento --bbs-shared-home de gh bbs2gh migrate-repo como o diretório inicial compartilhado do Bitbucket Server ou do Data Center. O diretório base compartilhado padrão é /var/atlassian/application-data/bitbucket/shared, mas a configuração pode ser diferente.

Você pode identificar o diretório base compartilhado no Bitbucket Server.

  1. Navegue até a área Administração da instância do Bitbucket Server ou do Data Center.
  2. Na barra lateral, em "Sistema", clique em Armazenamento.
  3. Em "Diretório compartilhado", veja o local do diretório base compartilhado do servidor.

Se você estiver executando o Bitbucket Data Center no modo de cluster com várias anotações, o diretório compartilhado será compartilhado entre os nós de cluster e será montado no mesmo local em cada nó.

Repository rule violations found erro(s)

Se você receber um erro Repository rule violations found, como GH013: Repository rule violations found for refs/heads/main, isso indicará que os dados do repositório de origem entram em conflito com os conjuntos de regras configurados na organização de destino. Para obter mais informações, confira "Sobre os conjuntos de regras".

Você pode desabilitar temporariamente seus conjuntos de regras durante a migração ou usar o modo de bypass ou a lista de bypass para isentar a migração das regras configuradas. Para obter mais informações, confira "Como gerenciar conjuntos de regras para repositórios na sua organização".

Your push would publish a private email address erro(s)

Se você receber o erro Git source migration failed com GH007: Your push would publish a private email address, a origem do Git que você está tentando migrar incluirá commits criados por um endereço de email que foi impedido de ser enviado por push para GitHub. Para obter mais informações, confira "Bloquear pushes de linha de comando que mostrem endereços de e-mail pessoais."

Para resolve esse erro, você pode reescrever o histórico do Git para remover o endereço de email ou desabilitar a configuração "Bloquear os pushes de linha de comando que expõem o email".

Noções básicas sobre avisos de log de migração

Mesmo que a migração seja bem-sucedida, você ainda deve revisar o log de migração para verificar se há avisos.

Os avisos no log de migração apontam para itens específicos dentro do repositório que não puderam ser migrados. Para obter mais informações, confira "Como acessar os logs de migração do GitHub Enterprise Importer".

Observação: se o problema "Log de Migração" incluir "Migração concluída" na parte inferior, isso indicará que o repositório foi migrado. Avisos indicam apenas que itens específicos do repositório, como um comentário em uma solicitação de pull, podem não ter sido migrados corretamente.

Aviso: “Metadados do repositório grandes demais para a migração”

Se você observar o erro "Metadados do repositório grandes demais para a migração" no problema "Log de migração" ou na GitHub CLI, isso indicará que o seu repositório excede o tamanho máximo de arquivo de 10 GB. Isso geralmente é causado por ativos de lançamento grandes. Tente excluir versões da migração com o sinalizador --skip-releases para o comando migrate-repo.

Aviso: "Comentário não incluído na comparação"

Se você estiver migrando do Azure DevOps, os comentários de solicitação de pull em linhas que nunca foram alteradas na solicitação de pull não poderão ser migrados para o GitHub. Você verá esse aviso para cada comentário que não pode ser migrado por esse motivo.

Observação: somente os comentários nas linhas que não foram alteradas em uma solicitação de pull são afetados por essa limitação. Os comentários nas linhas que foram alteradas em uma solicitação de pull são migrados.

Lembre-se de que os comentários afetados não estarão no repositório migrado, mas esses avisos não exigem outras ações da sua parte.

Aviso: "Revisão da solicitação de pull... não pôde ser importado devido a um erro REVIEW_THREAD_MISSING_END_COMMIT_OID"

Esse aviso ocorre quando uma revisão de solicitação de pull não pôde ser migrada porque a confirmação à qual a revisão está anexada não existe mais.

Isso geralmente acontece quando as confirmações foram removidas com um push forçado ou uma ramificação foi excluída.

Nesse caso, os comentários não são perdidos, mas são migrados como comentários de solicitação de pull embutidos para preservar o histórico, em vez de como uma revisão anexada a uma confirmação específica.

As referências de equipe são desfeitas após uma migração da organização

As referências às equipes, como @octo-org/octo-team, não são atualizadas como parte de uma migração da organização. Isso pode causar problemas na organização de destino, como arquivos CODEOWNERS que não funcionam conforme o esperado.

Você pode atualizar essas referências após a migração ou preservar os nomes da sua equipe renomeando a organização de origem para que possa usar o nome original da organização de destino.

Por exemplo, se a sua organização de origem for @octo-org e o arquivo CODEOWNERS incluir uma referência à equipe @octo-org/octo-team, você poderá renomear a organização de origem para @octo-org-temp antes da migração, permitindo que você use @octo-org como o nome da nova organização. Em seguida, a equipe migrada será chamada @octo-org/octo-team. O arquivo CODEOWNERS no repositório migrado funcionará conforme o esperado.

Repositórios bloqueados

Após uma migração, você pode descobrir que seus repositórios de origem ou destino estão bloqueados, desabilitando o acesso ao código do repositório e a todos os seus recursos, como problemas e solicitações de pull. Para obter mais informações sobre os repositórios bloqueados, confira "Sobre repositórios bloqueados."

O processo de desbloqueio de um repositório depende do produto GitHub em que o repositório está armazenado.

  • Se o repositório bloqueado estiver em GitHub Enterprise Server, um administrador do site poderá desbloquear o repositório usando o painel de administração do site. Para obter mais informações, confira "Bloquear um repositório" na documentação do GitHub Enterprise Server.
  • Se o repositório bloqueado estiver em GitHub.com, você poderá entrar em contato com conosco por meio do Portal de suporte do GitHub para desbloquear o repositório.

Nota: se a migração falhou, nem todos os dados foram migrados. Se você optar por desbloquear e usar o repositório, haverá perda de dados. Excluir o repositório bloqueado e tentar novamente a migração talvez seja uma opção melhor.

Como entrar em contato com o Suporte do GitHub

Se você ainda não conseguir resolver o problema depois de experimentar as etapas de solução de problemas acima, entre em contato com o Suporte do GitHub por meio do Portal de Suporte do GitHub.