Résolution des problèmes de votre migration avec GitHub Enterprise Importer

Si votre migration échoue ou produit des résultats inattendus, vous pouvez essayer les étapes de résolution des problèmes courantes.

Dans cet article

À propos des étapes de résolution des problèmes de GitHub Enterprise Importer

Si votre migration échoue ou produit des résultats inattendus, essayez les premières étapes de résolution des problèmes ci-dessous, qui arrivent généralement à résoudre divers problèmes. Si ces premières étapes ne résolvent pas votre problème, recherchez les messages d’erreur dans les journaux de votre migration. Ensuite, recherchez le message d’erreur dans cet article et essayez les étapes de résolution.

Si vous ne parvenez pas à résoudre votre problème après avoir essayé les étapes de résolution des problèmes pour le message d’erreur, vous pouvez contacter le Support GitHub.

Premières étapes de résolution des problèmes

Avant d’investiguer plus en profondeur, essayez ces étapes de résolution des problèmes qui permettent généralement de résoudre divers problèmes.

  1. Vérifiez que vous utilisez la dernière version de l’extension GitHub CLI que vous utilisez pour la migration. Si ce n’est pas le cas, effectuez une mise à niveau vers la dernière version.

  2. Veillez à répondre à toutes les conditions d’accès. Pour plus d'informations, consultez l'article approprié pour votre chemin de migration.

  3. Essayez de réexécuter la migration. Certains problèmes de migration sont temporaires, et une deuxième tentative peut fonctionner.

  4. Essayez d’exécuter une migration sur un autre dépôt avec des données similaires. Cela permet de déterminer si le problème est propre au référentiel ou s’il s’agit d’un problème de forme de données plus large.

Si ces étapes ne résolvent pas votre problème, consultez les journaux de migration des messages d’erreur. Le journal que vous devez consulter dépend de l’échec ou de la réussite de votre migration.

Résolution des problèmes de migration ayant échoué

Si votre migration échoue, passez en revue les entrées de journal détaillées produites par GitHub CLI pour chaque migration. Le fichier journal est enregistré dans le même répertoire que celui où vous avez exécuté la migration.

Le journal contient un enregistrement de chaque commande que vous avez émise et de toutes les demandes d’API que GitHub CLI a effectuées en réponse. Les échecs et les messages d’erreur apparaissent normalement vers la fin du journal.

Impossible d’exécuter la migration

Si vous voyez une erreur comme No access to createMigrationMutation ou Missing permissions, votre compte personnel ne dispose pas de l’accès requis pour exécuter la migration. Vérifiez que vous êtes propriétaire d’organisation ou que vous avez reçu le rôle de migrateur. Pour plus d’informations sur l’octroi du rôle de migrateur, consultez « À propos de GitHub Enterprise Importer ».

Remarque : Si vous effectuez une migration entre produits GitHub, vérifiez que vous êtes propriétaire d’organisation ou que vous avez reçu le rôle de migrateur pour les organisations source et cible.

La ressource est protégée par la mise en application de SAML dans l’organisation

Cette erreur indique que l’utilisation d’un personal access token que vous avez fourni à GitHub CLI doit être autorisée avec l’authentification unique SAML. Pour plus d’informations, consultez « Autorisation d’un jeton d’accès personnel à utiliser avec l’authentification unique SAML ».

Réponse 401 Unauthorized

Les échecs qui incluent un code d’état 401 indiquent généralement que le personal access token que vous avez fourni à GitHub CLI n’a pas les étendues requises. Vérifiez les champs d'application des personal access token que vous avez fournis. Pour plus d'informations sur les étendues requises, consultez l'article approprié pour votre chemin de migration.

Réponse de 404 Not Found

Les échecs qui incluent un code d’état 404 indiquent généralement une faute de frappe dans l’une de vos commandes. Passez en revue le journal de migration pour connaître la commande exacte que vous avez entrée et recherchez les fautes de frappe dans le dépôt source, l’organisation ou le projet.

Réponse Archive generation failed

Si vous recevez une réponse Archive generation failed... lors de la migration à partir de GitHub Enterprise Server, votre dépôt est probablement trop volumineux. Pour plus d’informations sur les tailles limites des dépôts, consultez « Informations sur les migrations entre les produits GitHub ».

Tout d’abord, essayez d’exclure les mises en production de la migration à l’aide de l’indicateur --skip-releases avec la commande migrate-repo.

Si cela ne fonctionne pas, nous vous recommandons d’effectuer une mise à niveau vers GitHub Enterprise Server 3.8.0 ou ultérieur. Si vous ne parvenez pas à effectuer une mise à niveau, une autre option consiste à générer manuellement vos archives de dépôt à l’aide de ghe-migrator :

  1. Générez une archive de migration pour votre dépôt. Vous ne devez exporter qu’un seul dépôt à la fois. Pour obtenir des instructions, consultez « Exportation de données de migration à partir de votre entreprise » dans la documentation GitHub Enterprise Server.
  2. Chargez votre archive de migration sur le fournisseur de stockage de blobs de votre choix.
  3. Générez une URL de courte durée pour votre archive de migration accessible sur GitHub.com, telle qu’une URL pré-signée AWS S3 ou une URL SAS Stockage Blob Azure.
  4. Appelez la commande migrate-repo avec les indicateurs --git-archive-url et --metadata-archive-url définis sur l’URL de votre archive à l’étape précédente.

cipher name is not supported erreurs

Si vous effectuez une migration à partir de Bitbucket Server et que vous recevez une erreur comme cipher name aes256-ctr for openssh key file is not supported lors de l’exécution d’une migration, votre clé privée SSH utilise un chiffrement non pris en charge. Pour plus d’informations sur les chiffrements pris en charge, consultez « Gestion de l'accès pour une migration à partir de Bitbucket Server ».

Pour générer une nouvelle paire de clés SSH compatible, exécutez la commande suivante :

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

Après avoir généré une nouvelle paire de clés SSH, avant de pouvoir utiliser la clé, vous devez ajouter la clé publique aux authorized_keys de votre instance Bitbucket Server.

Subsystem 'sftp' could not be executed erreurs

Si vous migrez à partir de Bitbucket Server et que vous recevez une erreur de type Subsystem 'sftp' could not be executed, SFTP n’est pas activé sur votre serveur ou votre compte d’utilisateur n’a pas d’accès SFTP.

Vous devez contacter votre administrateur de serveur et lui demander d’activer l’accès SFTP pour votre compte d’utilisateur.

Source export archive... does not exist erreurs

Si vous effectuez une migration depuis Bitbucket Server et que vous recevez une erreur comme Source export archive (/var/atlassian/application-data/bitbucket/shared/migration/export/Bitbucket_export_1.tar) does not exist, GitHub CLI recherche votre archive de migration au mauvais emplacement sur votre instance Bitbucket Server.

Pour résoudre ce problème, choisissez le répertoire de base partagé de Bitbucket Server ou de votre centre de données comme argument --bbs-shared-home pour gh bbs2gh migrate-repo. Le répertoire de base partagé par défaut est /var/atlassian/application-data/bitbucket/shared, mais votre configuration peut être différente.

Vous pouvez identifier le répertoire de base partagé dans Bitbucket Server.

  1. Accédez à la zone Administration de votre instance Bitbucket Serveur ou de votre centre de données.
  2. Dans la barre latérale, sous Système, cliquez sur Stockage.
  3. Sous « Répertoire partagé », affichez l’emplacement du répertoire de base partagé de votre serveur.

Si vous exécutez Bitbucket Data Center en mode cluster avec plusieurs remarques, votre répertoire est partagé entre les nœuds de cluster et doit être monté au même emplacement sur chaque nœud.

Repository rule violations found erreurs

Si vous recevez une erreur Repository rule violations found, telle que GH013: Repository rule violations found for refs/heads/main, les données du référentiel d’origine sont en conflit avec les ensembles de règles configurés sur l’organisation de destination. Pour plus d’informations, consultez « À propos des ensembles de règles ».

Vous pouvez temporairement désactiver vos ensembles de règles pendant votre migration, ou utiliser le mode de contournement ou la liste de contournement pour exempter votre migration des règles configurées. Pour plus d’informations, consultez « Gestion des ensembles de règles pour les dépôts de votre organisation ».

Your push would publish a private email address erreurs

Si vous recevez une erreur Git source migration failed avec GH007: Your push would publish a private email address, la source Git que vous essayez de migrer inclut les validations créées par une adresse e-mail que vous avez empêchée d’être poussée vers GitHub. Pour plus d’informations, consultez « Blocage des poussées de ligne de commande qui exposent votre adresse e-mail personnelle ».

Pour résoudre cette erreur, vous pouvez réécrire l’historique Git pour supprimer l’adresse e-mail ou désactiver le paramètre « Bloquer les envois de ligne de commande qui exposent mon adresse e-mail ».

Comprendre les avertissements du journal de migration

Même si la migration réussit, vous devez toujours consulter le journal de migration pour vérifier s'il y a des avertissements.

Les avertissements dans le journal de migration indiquent les éléments spécifiques du référentiel qui n'ont pas pu être migrés. Pour plus d’informations, consultez « Accès à vos journaux de migration pour GitHub Enterprise Importer ».

Remarque : Si le problème « Journal de migration » inclut « Migration terminée » en bas, le dépôt a été migré. Les messages d'erreur indiquent uniquement que des éléments spécifiques dans le référentiel, notamment un commentaire sur une demande de tirage, peuvent ne pas avoir été correctement migrés.

Avertissement : « Les métadonnées du référentiel sont trop volumineuses pour être migrées »

Si vous voyez « Métadonnées de dépôt trop volumineuses à migrer » dans le problème « Journal de migration » ou dans GitHub CLI, votre dépôt dépasse la taille d’archive maximale de 10 Go. Cela est souvent dû à des ressources de mise en production volumineuses. Essayez d’exclure les mises en production de la migration avec l’indicateur --skip-releases de la commande migrate-repo.

Avertissement : « Le commentaire n'est pas dans diff »

Si vous effectuez la migration depuis Azure DevOps, les commentaires de demande de tirage sur des lignes qui n’ont jamais été modifiées dans la demande de tirage ne peuvent pas être migrés vers GitHub. Vous verrez cet avertissement pour chaque commentaire qui ne peut pas être migré pour cette raison.

Remarque : Seuls les commentaires sur les lignes qui n’ont pas été modifiées dans une demande de tirage sont affectés par cette limitation. Les commentaires sur les lignes qui ont été modifiées dans une demande de tirage sont migrés.

Veuillez noter que les commentaires affectés ne seront pas dans le dépôt migré, mais que ces avertissements ne demandent pas d’action supplémentaire de votre part.

Avertissement : « La révision de demande de tirage...n'a pas pu être importée en raison de l'erreur REVIEW_THREAD_MISSING_END_COMMIT_OID »

Cet avertissement se produit lorsqu'une révision de demande de tirage n'a pas pu être migrée, car la validation à laquelle la révision est attachée n'existe plus.

Cela se produit généralement lorsque les validations ont été supprimées avec une poussée forcée, ou qu'une branche a été supprimée.

Dans ce cas, les commentaires ne sont pas perdus, mais sont migrés en tant que commentaires de demande de tirage (pull request) en ligne pour préserver l'historique, plutôt qu'en tant que révision attachée à une validation spécifique.

Les références d’équipe sont rompues après une migration d’organisation

Les références à des équipes, telles que @octo-org/octo-team, ne sont pas mises à jour dans le cadre d’une migration d’organisation. Cela risque d’entraîner des problèmes dans l’organisation de destination, comme par exemple les fichiers CODEOWNERS qui ne fonctionnent pas comme prévu.

Vous pouvez soit mettre à jour ces références après la migration, soit conserver vos noms d’équipe en renommant l’organisation source afin de pouvoir utiliser le nom d’origine de votre organisation de destination.

Par exemple, si votre organisation source s’appelle @octo-org et que votre fichier CODEOWNERS inclut une référence à l’équipe @octo-org/octo-team, vous pouvez renommer l’organisation source @octo-org-temp avant votre migration, ce qui vous permet d’utiliser @octo-org comme nom de la nouvelle organisation. Ensuite, l’équipe migrée sera appelée @octo-org/octo-team et le fichier CODEOWNERS dans le dépôt migré fonctionnera comme prévu.

Dépôts verrouillés

Après une migration, vous constaterez peut-être que vos dépôts source ou de destination sont verrouillés, ce qui désactive l’accès au code du dépôt et à toutes ses ressources, comme les problèmes et les demandes de tirage. Pour plus d’informations sur les dépôts verrouillés, consultez « À propos des dépôts verrouillés ».

Le processus de déverrouillage d’un dépôt dépend du produit GitHub où le dépôt est stocké.

  • Si le dépôt verrouillé se trouve sur GitHub Enterprise Server, un administrateur de site peut déverrouiller le dépôt à l’aide du tableau de bord de l’administrateur de site. Pour plus d’informations, consultez « Verrouillage d’un dépôt » dans la documentation GitHub Enterprise Server.
  • Si le dépôt verrouillé se trouve sur GitHub.com, vous pouvez contacter pour déverrouiller le dépôt.

Remarque : Si votre migration a échoué, vos données n’ont pas toutes été migrées. Si vous choisissez de déverrouiller et d’utiliser le dépôt, des données seront perdues. La suppression du dépôt verrouillé et une nouvelle tentative de migration peuvent se révéler être une meilleure solution.

Contacter le Support GitHub

Si vous ne parvenez toujours pas à résoudre votre problème après avoir essayé les étapes de résolution des problèmes ci-dessus, vous pouvez contacter le Support GitHub via le Portail de support GitHub.