Si votre migration rencontre un problème, vérifiez l’état de la migration avec gh elm migration status --migration-id MIGRATION-ID et passez en revue les informations d’erreur.
États et actions recommandées
| État | Sens | Action recommandée |
|---|---|---|
| Créée | La migration a été créée, mais pas encore démarrée | Exécutez gh elm migration start |
| En file d'attente | La migration attend le démarrage | Wait |
| Exportation | Les données sont exportées à partir de la source | Surveiller avec gh elm migration status |
| Traitement | Les données exportées sont importées dans la destination | Surveiller avec gh elm migration status |
| Prêt pour le basculement | La migration initiale est terminée et prête pour le basculement | Quand vous êtes prêt, exécutez gh elm migration cutover |
| Basculement | Le référentiel source est archivé et les modifications restantes sont appliquées à la destination | Moniteur; l’état passe à Terminé |
| Completed | La migration s’est terminée avec succès | Vérifier le référentiel de destination et récupérer des mannequins |
| Échec | La migration a rencontré un échec irrécupérable | Examiner l’erreur (voir ci-dessous) |
| suspendu | La migration est suspendue | Vérifier la raison de pause et résoudre (voir ci-dessous) |
| Terminé | La migration a été annulée | N/A |
| Détérioré | La destination est inaccessible | Vérifier la connectivité réseau entre l’appliance GitHub Enterprise Server et GHE.com (voir ci-dessous) |
L’état de la migration est « Échec »
Une migration entre dans l’état Échec lorsqu’une erreur irrécupérable l’empêche de continuer. Il s’agit d’une différence entre les ressources individuelles qui n’ont pas pu être importées ; une migration ayant échoué signifie que la migration elle-même ne peut pas continuer.
Pour enquêter, exécutez gh elm migration status --migration-id MIGRATION-ID et passez en revue les détails de l'erreur dans la réponse. Chaque échec inclut un ID de corrélation au format (Correlation ID for Support: UUID). Si vous contactez Support GitHub, fournissez cet ID afin que l’équipe du support technique puisse examiner.
Après avoir résolu le problème sous-jacent, abandonnez la migration ayant échoué avec gh elm migration cancel --migration-id MIGRATION-ID et démarrez une nouvelle migration.
Le statut de la migration est « En pause »
Une migration entre dans l’état suspendu lorsqu’un problème nécessite votre intervention avant de pouvoir continuer. Exécutez gh elm migration status --migration-id MIGRATION-ID et vérifiez la raison de la pause.
Raisons courantes de pause :
- Expiration des informations d’identification : l’une des informations personal access tokens (classic) d’identification a expiré. Créez un jeton avec les étendues requises et mettez-le à jour avec
gh elm credential update. Redémarrez ensuite la migration. - Limitation du débit : la migration a atteint les limites de débit de l’API. Patientez quelques minutes, puis redémarrez.
Pour redémarrer une migration suspendue après avoir résolu le problème sous-jacent :
gh elm migration start --migration-id MIGRATION-ID
L’état de la migration est « Détérioré »
Un état détérioré signifie que le service de migration sur l’appliance GitHub Enterprise Server ne peut pas atteindre l’entreprise de destination. La migration se poursuit côté source, mais l’état de destination est inconnu.
Vérifiez la connectivité réseau entre l’appliance GitHub Enterprise Server et votre sous-domaine, GHE.compuis réexécutez gh elm migration status --migration-id MIGRATION-ID . La réponse d’état inclut un horodatage pour le dernier contact réussi avec la destination, ce qui peut vous aider à évaluer la durée pendant laquelle le problème de connectivité s’est produit.
Migration bloquée dans « Exportation »
Si votre migration reste dans l’état Exportation sans modification de progression pendant 30 minutes ou plus, l’exportateur peut être bloqué.
-
Exécutez
gh elm migration status --migration-id MIGRATION-IDet notez si les nombres de ressources changent. -
Si le nombre est statique, vérifiez la connectivité réseau de l’appliance à la destination.
-
Passez en revue les journaux d’activité de l’exportateur sur l’appliance GitHub Enterprise Server (nécessite un accès administrateur SSH) :
Shell journalctl -t elm-exporter-backfiller --since "1 hour ago" | tail -50 journalctl -t elm-exporter-sender --since "1 hour ago" | tail -50
journalctl -t elm-exporter-backfiller --since "1 hour ago" | tail -50 journalctl -t elm-exporter-sender --since "1 hour ago" | tail -50 -
Si la tâche d’exportation s’est arrêtée de manière inattendue, elle devrait se relancer automatiquement. Si ce n’est pas le cas, contactez Support GitHub.
Synchronisation Git non terminée
Si gh elm migration status indique que la commande push Git initiale n’est pas terminée au bout d’un long moment, vérifiez les journaux du synchroniseur Git :
journalctl -t elm-exporter-git-syncer --since "2 hours ago"
journalctl -t elm-exporter-git-syncer --since "2 hours ago"
Recherchez :
connection refused: problème réseau entre l’appliance GitHub Enterprise Server et la destination. Vérifiez les règles de pare-feu et la résolution DNS.authentication failed: Le personal access token (classic) peut ne pas disposer des autorisations requises ou avoir expiré.remote: error: la destination peut rejeter le push. Contactez Support GitHub en fournissant les détails de l’erreur.
Certaines ressources n’ont pas pu être importées
Les ressources individuelles peuvent ne pas être importées sans provoquer l’échec de la migration globale. Vous pouvez voir le nombre de ressources ayant échoué dans la sortie de gh elm migration status --migration-id MIGRATION-ID.
Les ressources ayant échoué sont affichées uniquement après que toutes les nouvelles tentatives automatiques ont été épuisées, les échecs que vous voyez sont donc confirmés comme non résolus sans intervention. Passez en revue les détails de l’erreur dans la réponse d’état : chaque ressource ayant échoué dans le remplissage rétroactif ou les mises à jour en direct s'affichera "state": "failed".
Si le nombre et les types de ressources ayant échoué sont acceptables, vous pouvez procéder au basculement. Si ce n’est pas le cas, abandonnez la migration, résolvez le problème sous-jacent, puis démarrez une nouvelle migration.
Le basculement a échoué et le dépôt source n’est pas disponible
Si un basculement échoue une fois que le référentiel source a été archivé, le ELM service tentera de désarchiver le référentiel. En cas d’échec, un administrateur de référentiel peut annuler l’archivage du référentiel. Consultez « Archivage de référentiels ».
N’oubliez pas que l’annulation de l’archivage d’un référentiel entraîne une charge supplémentaire sur l’instance, car tous les problèmes et demandes de tirage dans le référentiel seront réindexés dans Elasticsearch.
Une fois le référentiel source désarchivé, vous pouvez soit réessayer le basculement à l’aide de gh elm migration cutover --migration-id MIGRATION-ID, soit abandonner la migration à l’aide de gh elm migration cancel --migration-id MIGRATION-ID et démarrer une nouvelle migration lorsque vous serez prêt.
La migration doit être redémarrée en raison d’un « force push »
Si quelqu’un effectue un "force push" sur la branche principale du dépôt source pendant qu’une migration est en cours, la synchronisation Git entre la source et la destination est rompue. Les « force pushes » réécrivent l’historique des commits d’une manière qui ne permet pas une synchronisation incrémentale.
Dans ce cas, interrompez la migration avec gh elm migration cancel --migration-id MIGRATION-ID et démarrez une nouvelle migration. Avant de redémarrer, communiquez à votre équipe que les push forcés vers la branche par défaut ne sont pas autorisés pendant qu’une migration est active.
Le jeton d’accès à la migration a été rejeté
Si votre migration échoue avec une erreur d’authentification, vérifiez que :
- Les deux jetons source et de destination sont personal access tokens (classic). Fine-grained personal access tokens ne sont pas pris en charge.
- Si l’organisation de destination applique l’authentification unique SAML, le jeton doit être autorisé pour l’authentification unique.
- Les deux jetons ont les étendues spécifiées dans Migration de votre référentiel avec Enterprise Live Migrations.
Si vous avez récemment pivoté un jeton, la migration récupère automatiquement de nouvelles informations d’identification. Vous n’avez pas besoin d’exécuter ghe-config-apply ou de redémarrer le service de migration.
GitHub CLI le jeton d’accès a été rejeté
Enterprise Live Migrations utilise deux ensembles d’informations d’identification. Cette section s’applique aux jetons d’opérateur créés à l’étape 2 et stockés localement par gh elm configure.
L’opérateur doit utiliser un personal access token (classic) pour chaque point de terminaison :
- Le jeton d’opérateur source doit être créé sur GitHub Enterprise Server.
- Le jeton d’opérateur cible doit être créé sur GHE.com.
- Les deux tokens ont les portées spécifiées dans Migration de votre référentiel avec Enterprise Live Migrations.
- Le propriétaire du jeton doit être administrateur de l’entreprise correspondante. La sélection d’une portée ne confère pas à l’utilisateur de droits d’administration.
- Fine-grained personal access tokens ne sont pas pris en charge.
Réponses courantes
| Response | Sens | Correctif |
|---|---|---|
401 Bad credentials | Le point de terminaison n’a pas pu authentifier le jeton. Les étendues d’autorisation n’ont pas encore été évaluées. | Vérifiez que le jeton n’a pas expiré ou a été révoqué, qu’il a été copié complètement et que les jetons source et cible n’ont pas été échangés. Vérifiez que chaque jeton a été créé sur l’hôte où il est utilisé. |
403 Forbidden | Le jeton a été authentifié, mais son utilisateur ou ses étendues n’autorisent pas l’opération. | Utilisez un personal access token (classic) avec admin:enterprise. Vérifiez que le propriétaire du jeton est un administrateur de l’entreprise. Si l’authentification unique SAML s’applique, autorisez le jeton pour l’authentification unique. |
Resource not accessible by personal access token | Le type de jeton ou les autorisations ne sont pas pris en charge. Cela se produit généralement avec un fine-grained personal access token. | Remplacez-le par un personal access token (classic) qui a admin:enterprise. |
404 Not Found | La demande peut utiliser l’URL d’API incorrecte ou Enterprise Live Migrations n’est pas activée pour l’entreprise de destination. | Pour GHE.com, utilisez l’URL de l’API du locataire, telle que https:/, sans barre oblique finale. Vérifiez également l’URL de l’API source. Si les deux URL sont correctes, contactez Support GitHub pour confirmer que Enterprise Live Migrations est activé. |
Valider les jetons indépendamment
Testez chaque jeton sur le /user point de terminaison avant de l’utiliser avec Enterprise Live Migrations. Ces commandes impriment les en-têtes de réponse, mais ignorent le corps de la réponse.
Pour le jeton source (GitHub Enterprise Server) :
curl --silent --show-error --output /dev/null --dump-header - \
--header "Authorization: Bearer $SOURCE_OPERATOR_TOKEN" \
"$SOURCE_API_URL/user"
Pour le jeton cible :
curl --silent --show-error --output /dev/null --dump-header - \
--header "Authorization: Bearer $TARGET_OPERATOR_TOKEN" \
"$TARGET_API_URL/user"
Chaque requête doit retourner 200 OK. L’en-tête X-OAuth-Scopes de réponse doit inclure admin:enterprise.
Si /user renvoie Enterprise Live Migrations, mais qu’une commande 200 OK renvoie 401 Bad credentials, il se peut que l’interface de ligne de commande ait enregistré un jeton différent ou une URL différente. Réexécutez et associez gh elm configure soigneusement chaque jeton à son point de terminaison correspondant.
Les tokens d’opérateur sont stockés localement par la CLI Enterprise Live Migrations. Après la rotation d’un jeton d’opérateur, réexécutez gh elm configure ou fournissez les informations d’identification de remplacement à l’aide des options de ligne de commande appropriées.
Cela diffère des jetons de service de migration configurés à l’étape 4. Les informations d’identification mises à jour du service de migration sont prises en compte automatiquement et ne nécessitent ni ghe-config-apply ni le redémarrage du service de migration.
N’incluez pas de jetons d’accès dans les fichiers journaux, les captures d’écran, les archives de support ou les demandes de support. Si le problème persiste, fournissez Support GitHub l’état HTTP, le nom d’hôte du point de terminaison, l’ID de migration, l’horodatage avec le fuseau horaire et tout ID de corrélation, mais pas le jeton.
L’URL GHES source a été rejetée
Enterprise Live Migrations nécessite l’URL GitHub Enterprise Server pour utiliser HTTPS. Si l’URL est configurée avec HTTP, la migration échoue à la validation préliminaire.
Collecte des journaux d’activité pour la prise en charge
Lorsque vous contactez Support GitHub, les éléments les plus utiles sont les suivants :
- Offre groupée de support (par défaut) : Exécutez
ghe-support-bundle -usur l’appliance GitHub Enterprise Server . Cela capture automatiquement tous les Enterprise Live Migrations logs. - Sortie de l’état de la migration :
gh elm migration status --migration-id MIGRATION-ID - ID de migration et heure approximative d’échec (avec fuseau horaire)
- Tous les ID de corrélation des messages d’erreur
Si un bundle de support n’est pas possible, vous pouvez collecter les journaux manuellement :
journalctl -t elm-exporter-migration-manager --since "24 hours ago" > migration-manager.log journalctl -t elm-exporter-backfiller --since "24 hours ago" > backfiller.log journalctl -t elm-exporter-sender --since "24 hours ago" > sender.log journalctl -t elm-exporter-git-syncer --since "24 hours ago" > git-syncer.log
journalctl -t elm-exporter-migration-manager --since "24 hours ago" > migration-manager.log
journalctl -t elm-exporter-backfiller --since "24 hours ago" > backfiller.log
journalctl -t elm-exporter-sender --since "24 hours ago" > sender.log
journalctl -t elm-exporter-git-syncer --since "24 hours ago" > git-syncer.log