Behandeln von Problemen bei der Migration mit GitHub Enterprise Importer

Informationen zu Problembehandlungsschritten für GitHub Enterprise Importer

Wenn bei der Migration ein Fehler auftritt oder unerwartete Ergebnisse erzielt werden, führe die unten aufgeführten ersten Schritte zur Problembehandlung aus, mit denen in der Regel viele Probleme behoben werden können. Wenn diese ersten Schritte dein Problem nicht beheben, suche in den Protokollen für deine Migration nach Fehlermeldungen. Suche dann in diesem Artikel nach der Fehlermeldung, und probiere die Schritte zur Lösung aus.

Wenn du ein Problem nicht beheben kannst, indem du die Schritte zur Problembehandlung für eine Fehlermeldung ausgeführt hast, kannst du den GitHub-Support kontaktieren.

Erste Schritte zur Problembehandlung

Bevor du weitere Untersuchungen durchführst, führe die folgenden Schritte zur Problembehandlung aus, mit denen in der Regel viele Problemen behoben werden können.

1. Vergewissere dich, dass du für die Migration die neueste Version der GitHub CLI-Erweiterung verwendest. Führe andernfalls ein Upgrade auf die neueste Version aus.
2. Vergewissere dich, dass alle Zugriffsanforderungen erfüllt sind. Weitere Informationen findest du unter Verwalten des Zugriffs für GitHub Enterprise Importer.
3. Versuche, die Migration erneut auszuführen. Einige Migrationsprobleme sind nur vorübergehend, sodass ein zweiter Versuch Abhilfe schaffen kann.
4. Versuche, eine Migration in einem anderen Repository mit ähnlichen Daten auszuführen. Auf diese Weise kannst du feststellen, ob das Problem nur dieses Repository betrifft oder ein umfassenderes Problem mit der Datenform vorliegt.

Wenn das Problem durch diese Schritte nicht behoben wird, überprüfe das Migrationsprotokoll auf Fehlermeldungen. Welches Protokoll du überprüfen musst, hängt davon ab, ob die Migration fehlerhaft oder erfolgreich war.

Problembehandlung bei fehlerhaften Migrationsvorgängen

Wenn die Migration fehlerhaft war, überprüfe die ausführlichen Protokolleinträge, die von der GitHub CLI für jede Migration generiert werden. Die Protokolldatei wird im selben Verzeichnis gespeichert, in dem du die Migration ausgeführt hast.

Das Protokoll enthält einen Datensatz über jeden von dir ausgegebenen Befehl und alle API-Anforderungen, die die GitHub CLI als Antwort übermittelt hat. Fehler und Fehlermeldungen stehen normalerweise am Ende des Protokolls.

• Die Migration konnte nicht ausgeführt werden.
• Die Ressource wird durch SAML-Erzwingung der Organisation geschützt.
• Antwort 401 Unauthorized
• Antwort 404 Not Found
• Antwort Archive generation failed
• cipher name is not supported Fehler
• Subsystem 'sftp' could not be executed Fehler
• Source export archive... does not exist Fehler
• Repository rule violations found Fehler

Die Migration konnte nicht ausgeführt werden.

Wenn ein Fehler wie No access to createMigrationMutation oder Missing permissions angezeigt wird, verfügt dein persönliches Konto nicht über den erforderlichen Zugriff für die Migration. Stelle sicher, dass du entweder Besitzer*in der Organisation bist oder dir die Migrationsrolle zugewiesen wurde. Weitere Informationen zum Zuweisen der Migrationsrolle findest du unter Migrieren von Repositorys mit GitHub Enterprise Importer.

Die Ressource wird durch SAML-Erzwingung der Organisation geschützt.

Dieser Fehler weist darauf hin, dass ein personal access token, das du für GitHub CLI bereitgestellt hast, für die Verwendung mit einmaligem Anmelden mit SAML autorisiert werden muss. Weitere Informationen findest du unter Ein persönliches Zugriffstoken für die Verwendung mit SAML Single Sign-On autorisieren.

Antwort von 401 Unauthorized

Fehler, die den Statuscode 401 enthalten, weisen in der Regel darauf hin, dass das personal access token, das du in der GitHub CLI bereitgestellt hast, nicht die erforderlichen Bereiche umfasst. Überprüfe die Bereiche für die personal access token, die du für deine Quell- und Zielorganisation bereitgestellt hast. Weitere Informationen zu den erforderlichen Bereichen findest du unter Verwalten des Zugriffs für GitHub Enterprise Importer.

Antwort von 404 Not Found

Fehler, die den Statuscode 404 enthalten, weisen meist auf einen Tippfehler in einem deiner Befehle hin. Überprüfe das Migrationsprotokoll auf den genauen Befehl, den du eingegeben hast, und suche im Quellrepository, in der Organisation oder im Projekt nach Tippfehlern.

Antwort von Archive generation failed

Wenn du beim Migrieren von GitHub Enterprise Server eine Antwort mit Archive generation failed... erhältst, ist dein Repository wahrscheinlich zu groß. Weitere Informationen zu Grenzwerten für die Repositorygröße findest du unter Migrationsunterstützung für GitHub Enterprise Importer.

Versuche zunächst, Releases von der Migration auszuschließen, indem du das Flag --skip-releases mit dem Befehl migrate-repo verwendest.

Wenn dies nicht funktioniert, wird ein Upgrade auf GitHub Enterprise Server 3.8.0 oder höher empfohlen. Wenn du kein Upgrade durchführen kannst, besteht eine andere Möglichkeit darin, deine Repositoryarchive mit ghe-migrator manuell zu generieren:

1. Generiere ein Migrationsarchiv für dein Repository. Du solltest nur jeweils ein Repository gleichzeitig exportieren. Anweisungen findest du unter Exportieren von Migrationsdaten aus deinem Unternehmen.
2. Lade dein Migrationsarchiv in den Blobspeicheranbieter deiner Wahl hoch.
3. Generiere eine kurzlebige URL für dein Migrationsarchiv, auf die GitHub.com Zugriff hat, z. B. eine vorsignierte AWS S3-URL oder eine Azure Blob Storage-SAS-URL.
4. Rufe den Befehl migrate-repo mit den Flags --git-archive-url und --metadata-archive-url auf, die auf die URL deines Archivs aus dem vorherigen Schritt festgelegt sind.

cipher name is not supported Fehler

Wenn du bei einer Migration von Bitbucket Server eine Fehlermeldung wie cipher name aes256-ctr for openssh key file is not supported erhältst, verwendet dein privater SSH-Schlüssel ein nicht unterstütztes Verschlüsselungsverfahren. Weitere Informationen zu unterstützten Verschlüsselungsverfahren findest du unter Verwalten des Zugriffs für GitHub Enterprise Importer.

Führe den folgenden Befehl aus, um ein neues kompatibles SSH-Schlüsselpaar zu generieren:

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

Nachdem du ein neues SSH-Schlüsselpaar generiert hast, musst du den öffentlichen Schlüssel den authorized_keys der Bitbucket Server-Instanz hinzufügen, bevor du den Schlüssel verwenden kannst.

Subsystem 'sftp' could not be executed Fehler

Wenn du bei einer Migration von Bitbucket Server eine Fehlermeldung wie Subsystem 'sftp' could not be executed erhältst, ist SFTP auf deinem Server nicht aktiviert, oder dein Benutzerkonto verfügt nicht über SFTP-Zugriff.

Bitte deinen Serveradministrator bzw. deine Serveradministratorin, den SFTP-Zugriff für dein Benutzerkonto zu aktivieren.

Source export archive... does not exist Fehler

Wenn du von Bitbucket Server migrierst und eine Fehlermeldung wie Source export archive (/var/atlassian/application-data/bitbucket/shared/migration/export/Bitbucket_export_1.tar) does not exist erhältst, sucht der GitHub CLI an der falschen Stelle auf deiner Bitbucket Server-Instanz nach deinem Migrationsarchiv.

Um dieses Problem zu beheben, lege das --bbs-shared-home-Argument für gh bbs2gh migrate-repo für deine Bitbucket Server-Instanz oder das freigegebene Basisverzeichnis des Rechenzentrums fest. Das standardmäßig freigegebene Basisverzeichnis ist /var/atlassian/application-data/bitbucket/shared, aber deine Konfiguration kann anders sein.

Du kannst das freigegebene Basisverzeichnis in Bitbucket Server identifizieren.

1. Navigiere zum Verwaltungsbereich deiner Bitbucket Server-Instanz oder deines Rechenzentrums.
2. Klicke in der Randleiste unter „System“ auf „Speicher“.
3. Zeige unter „Freigegebenes Verzeichnis“ den Speicherort des freigegebenen Basisverzeichnisses deines Servers an.

Wenn du das Bitbucket-Rechenzentrum im Clustermodus mit mehreren Knoten ausführst, wird dein freigegebenes Verzeichnis von Clusterknoten geteilt und sollte auf jedem Knoten an demselben Speicherort eingebunden werden.

Repository rule violations found Fehler

Wenn dir eine Repository rule violations found-Fehlermeldung wie GH013: Repository rule violations found for refs/heads/main angezeigt wird, liegt ein Konflikt zwischen den Daten im Ursprungsrepository und Regelsätzen (öffentliche Betaversion) vor, die in der Zielorganisation konfiguriert sind. Weitere Informationen findest du unter Informationen zu Regelsätzen.

Du kannst deine Regelsätze während der Migration vorübergehend deaktivieren oder den Umgehungsmodus oder die Umgehungsliste verwenden, um deine konfigurierten Regeln von der Migration auszuschließen. Weitere Informationen findest du unter Managing rulesets for repositories in your organization.

Problembehandlung bei erfolgreichen Migrationsvorgängen

Wenn deine Migration erfolgreich war, aber unerwartete Ergebnisse erzielt hat, überprüfe das Migrationsprotokoll auf Fehlermeldungen. Weitere Informationen findest du unter Zugreifen auf die Migrationsprotokolle für GitHub Enterprise Importer.

• Zu große Repositorymetadaten für die Migration
• Kommentar nicht im Diff
• Pull Request Review-Thread nicht in Pull Request migriert
• Teamverweise nach einer Organisationsmigration beschädigt

Zu große Repositorymetadaten für die Migration

Wenn im Issue „Migrationsprotokoll“ oder in der GitHub CLI als Fehler zu große Repositorymetadaten angezeigt werden, überschreitet dein Repository die maximale Archivgröße von 10 GB. Dies wird häufig durch große Releaseressourcen verursacht. Versuche, Releases mit dem Flag --skip-releases für den Befehl migrate-repo von der Migration auszuschließen.

Kommentar nicht im Diff

Wenn du von Azure DevOps migrierst, können Pull Request-Kommentare auf Zeilen, die im Pull Request nie geändert wurden, nicht zu GitHub migriert werden. Diese Warnung wird für jeden Kommentar angezeigt, der aus diesem Grund nicht migriert werden kann.

Die betroffenen Kommentare sind zwar nicht im migrierten Repository enthalten, aber diese Warnungen erfordern keine weiteren Aktionen.

Pull Request Review-Thread nicht in Pull Request migriert

Diese Warnung ist eine allgemeinere Form von „Kommentar nicht im Diff“. Wenn diese Warnung angezeigt wird, konnte ein Kommentar in einer Datei in einem Pull Request aus einem anderen Grund als der oben beschriebene nicht migriert werden. In den meisten Fällen befand sich der Kommentar auf einer Zeile, die im Pull Request-Verlauf geändert wurde, dies aber durch eine nachfolgende Änderung am Pull Request nicht mehr galt.

• Der Kommentar befindet sich in einer Datei, die später im Pull Request-Verlauf gelöscht wurde.
• Der Kommentar bezieht sich auf Code, der an einer Stelle im Pull Request-Verlauf geändert wurde, aber der/die Autor*in hat später beschlossen, die Änderung zu entfernen.
• Der Pull Request wurde in einem einzelnen Commit zusammengeführt, wodurch verhindert wird, dass GitHub den Pull Request-Verlauf ordnungsgemäß erstellen kann, um den Kommentar wie erwartet einzufügen.

Dieses Problem betrifft am häufigsten geschlossene Pull Requests.

Die betroffenen Kommentare sind zwar nicht im migrierten Repository enthalten, aber diese Warnungen erfordern keine weiteren Aktionen.

Teamverweise nach einer Organisationsmigration beschädigt

Verweise auf Teams, z. B. @octo-org/octo-team, werden im Rahmen einer Organisationsmigration nicht aktualisiert. Dies kann zu Problemen in der Zielorganisation führen, da z. B. CODEOWNERS-Dateien nicht wie erwartet funktionieren.

Du kannst diese Verweise entweder nach der Migration aktualisieren, oder du kannst die Teamnamen beibehalten, indem du die Quellorganisation umbenennst und so den ursprünglichen Namen für deine Zielorganisation verwenden kannst.

Wenn deine Quellorganisation beispielsweise @octo-org heißt und deine CODEOWNERS-Datei einen Verweis auf das Team @octo-org/octo-team enthält, kannst du die Quellorganisation vor der Migration in @octo-org-temp umbenennen, sodass du @octo-org als Namen der neuen Organisation verwenden kannst. Das migrierte Team heißt dann @octo-org/octo-team, und die CODEOWNERS-Datei im migrierten Repository funktioniert wie erwartet.

Kontaktieren des GitHub-Supports

Wenn du das Problem mit obigen Schritten zur Problembehandlung nicht beheben konntest, kannst du den GitHub-Support über das GitHub-Supportportal kontaktieren.