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

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, confira "Como gerenciar o acesso do GitHub Enterprise Importer".
3. Tente executar a migração novamente. Alguns problemas de migrações são transitórios, e uma segunda tentativa poderá 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 você precisa verificar dependerá do fato de a migração ter falhado ou sido bem-sucedida.

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 a migração
• O recurso é protegido pela imposição do SAML da organização
• Resposta 401 Unauthorized
• Resposta 404 Not Found
• Resposta Archive generation failed
• Erro cipher name is not supported
• Erro Subsystem 'sftp' could not be executed
• Erro Source export archive... does not exist
• Erro Repository rule violations found

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 "Como migrar repositórios com o GitHub Enterprise Importer".

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 as organizações de origem e de destino. Para obter mais informações sobre os escopos necessários, confira "Como gerenciar o acesso do GitHub Enterprise Importer".

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 "Suporte à migração para o GitHub Enterprise Importer".

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".
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 "Como gerenciar o acesso do GitHub Enterprise Importer".

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

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 o 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 (versão beta pública) 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".

Solução de problemas de migrações bem-sucedidas

Se a migração for bem-sucedida, mas produzir resultados inesperados, analise o log de migração em busca de mensagens de erro. Para obter mais informações, confira "Como acessar os logs de migração do GitHub Enterprise Importer".

• Metadados do repositório grandes demais para a migração
• Comentário não incluído na comparação
• Conversa da revisão de solicitação de pull não migrada na solicitação de pull
• As referências de equipe são desfeitas após uma migração da organização

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.

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.

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.

Conversa da revisão de solicitação de pull não migrada na solicitação de pull

Esse aviso é uma forma mais genérica do "Comentário não incluído na comparação". Se você receber esse aviso, um comentário de um arquivo em uma solicitação de pull não poderá ser migrado por um motivo diferente do descrito acima. Na maioria das vezes, o comentário estava em uma linha que foi alterada em um ponto no histórico de solicitações de pull, mas depois a solicitação de pull foi alterada, de modo que esse não fosse mais o caso.

• O comentário está em um arquivo que foi excluído posteriormente no histórico de solicitações de pull.
• O comentário estava em um código que foi alterado em um ponto do histórico de solicitações de pull, mas o autor mais tarde decidiu remover a alteração.
• A solicitação de pull foi mesclada por squash em um só commit, o que impede que o GitHub consiga construir corretamente o histórico de solicitações de pull para colocar corretamente o comentário.

Esse problema afeta com mais frequência as solicitações de pull fechadas.

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.

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, e o arquivo CODEOWNERS no repositório migrado funcionará conforme o esperado.

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.