Informationen zu Repositorymigrationsvorgängen mit GitHub Enterprise Importer
Du kannst deine Migration entweder mit der GitHub CLI oder mit der API ausführen.
Die GitHub CLI vereinfacht den Migrationsprozess und wird für die meisten Kundinnen empfohlen. Fortgeschrittene Kundinnen, die viele Anpassungen vornehmen müssen, können die API verwenden, um eigene Integrationen mit dem GitHub Enterprise Importer zu erstellen.
Voraussetzungen
- Es wird dringend empfohlen, einen Testlauf deiner Migration durchzuführen und die Produktionsmigration bald danach abzuschließen. Mehr über Testläufe erfahren Sie unter Übersicht über die Migration zwischen GitHub-Produkten.
- Stellen Sie sicher, dass Sie die zu migrierenden Daten und die bekannten Supportbeschränkungen des Importer verstehen. Weitere Informationen finden Sie unter Informationen zu Migrationen zwischen GitHub-Produkten.
- Es ist zwar nicht erforderlich, die Arbeit während der Produktionsmigration zu unterbrechen, es wird aber empfohlen. Der Importer unterstützt keine Deltamigrationen, sodass Änderungen, die während der Migration vorgenommen werden, nicht migriert werden. Wenn du dich dafür entscheidest, die Arbeit während der Produktionsmigration nicht zu unterbrechen, musst du diese Änderungen manuell migrieren.
- Sowohl in der Quell- als auch in der Zielorganisation musst du entweder Organisationsbesitzer*in sein, oder dir muss die Migrationsrolle zugewiesen sein. Weitere Informationen findest du unter Verwalten des Zugriffs für eine Migration zwischen GitHub-Produkten.
Schritt 0: Vorbereiten der Verwendung der GraphQL-API von GitHub
Um GraphQL-Abfragen zu erstellen, musst du eigene Skripts schreiben oder einen HTTP-Client wie Insomnia verwenden.
Weitere Informationen zu den ersten Schritten mit der GitHub-GraphQL-API, einschließlich der Authentifizierung, findest du unter Erstellen von Aufrufen mit GraphQL.
Schritt 1: Abrufen der ownerId für dein Migrationsziel
Verwende als Organisationsbesitzer*in in GitHub Enterprise Cloud die Abfrage GetOrgInfo, um die ownerId (auch als Organisations-ID bezeichnet) für die Organisation zurückzugeben, der du den Besitz der migrierten Repositorys zuordnen möchtest. Du benötigst die ownerId, um das Migrationsziel anzugeben.
Abfrage GetOrgInfo
query(
$login: String!
){
organization (login: $login)
{
login
id
name
databaseId
}
}
| Abfragevariable | Beschreibung |
|---|---|
login | Name deiner Organisation. |
Antwort von GetOrgInfo
{
"data": {
"organization": {
"login": "Octo",
"id": "MDEyOk9yZ2FuaXphdGlvbjU2MTA=",
"name": "Octo-org",
"databaseId": 5610
}
}
}
In diesem Beispiel ist MDEyOk9yZ2FuaXphdGlvbjU2MTA= die Organisations-ID oder die ownerId, die du im nächsten Schritt verwendest.
Schritt 2: Ermitteln der Migrationsquelle
Du kannst eine Migrationsquelle mithilfe der Abfrage createMigrationSource einrichten. Du musst die ownerId oder die Organisations-ID angeben, die du mit der Abfrage GetOrgInfo abgerufen hast.
Deine Migrationsquelle ist eine Organisation auf GitHub.com.
createMigrationSource-Mutation
mutation createMigrationSource($name: String!, $ownerId: ID!) {
createMigrationSource(input: {name: $name, url: "https://github.com", ownerId: $ownerId, type: GITHUB_ARCHIVE}) {
migrationSource {
id
name
url
type
}
}
}
Hinweis: Stelle sicher, dass du GITHUB_ARCHIVE für type verwendest.
| Abfragevariable | Beschreibung |
|---|---|
name | Ein Name für deine Migrationsquelle. Dieser Name dient deiner eigenen Referenz, sodass du eine beliebige Zeichenfolge angeben kannst. |
ownerId | Die Organisations-ID deiner Organisation in GitHub Enterprise Cloud. |
Antwort von createMigrationSource
{
"data": {
"createMigrationSource": {
"migrationSource": {
"id": "MS_kgDaACQxYmYxOWU4Yi0wNzZmLTQ3NTMtOTdkZC1hNGUzZmYxN2U2YzA",
"name": "GitHub.com Source",
"url": "https://github.com",
"type": "GITHUB_SOURCE"
}
}
}
}
In diesem Beispiel ist MS_kgDaACQxYmYxOWU4Yi0wNzZmLTQ3NTMtOTdkZC1hNGUzZmYxN2U2YzA die ID der Migrationsquelle, die du im nächsten Schritt verwendest.
Schritt 3: Starten der Repositorymigration
Wenn du eine Migration startest, werden ein einzelnes Repository und die zugehörigen Daten zu einem neuen GitHub-Repository migriert, das du angibst.
Wenn du mehrere Repositorys gleichzeitig aus derselben Quellorganisation verschieben möchtest, kannst du mehrere Migrationsvorgänge in die Warteschlange einreihen. Du kannst bis zu fünf Migrationsvorgänge gleichzeitig ausführen.
startRepositoryMigration-Mutation
mutation startRepositoryMigration (
$sourceId: ID!,
$ownerId: ID!,
$sourceRepositoryUrl: URI!,
$repositoryName: String!,
$continueOnError: Boolean!,
$accessToken: String!,
$githubPat: String!,
$targetRepoVisibility: String!
){
startRepositoryMigration( input: {
sourceId: $sourceId,
ownerId: $ownerId,
repositoryName: $repositoryName,
continueOnError: $continueOnError,
accessToken: $accessToken,
githubPat: $githubPat,
targetRepoVisibility: $targetRepoVisibility
sourceRepositoryUrl: $sourceRepositoryUrl,
}) {
repositoryMigration {
id
migrationSource {
id
name
type
}
sourceUrl
}
}
}
| Abfragevariable | Beschreibung |
|---|---|
sourceId | Die id deiner Migrationsquelle, die von der createMigrationSource-Mutation zurückgegeben wurde. |
ownerId | Die Organisations-ID deiner Organisation in GitHub Enterprise Cloud. |
repositoryName | Ein benutzerdefinierter eindeutiger Repositoryname, der derzeit von keinem deiner Repositorys im Besitz der Organisation auf GitHub Enterprise Cloud verwendet wird. Wenn die Migration abgeschlossen oder beendet wurde, wird ein Fehlerprotokollierungsproblem in diesem Repository erstellt. |
continueOnError | Migrationseinstellung, mit der die Migration fortgesetzt werden kann, wenn Fehler auftreten, die nicht dazu führen, dass die Migration fehlerhaft wird. Muss true oder false sein. Es wird dringend empfohlen continueOnError auf true festzulegen, damit die Migration fortgesetzt wird, es sei denn, der Importer kann die Git-Quelle nicht verschieben oder der Importer hat die Verbindung unterbrochen und kann die Verbindung nicht wiederherstellen, um die Migration abzuschließen. |
githubPat | Das personal access token für deine Zielorganisation auf GitHub Enterprise Cloud. |
accessToken | Das personal access token für deine Quelle. |
targetRepoVisibility | Die Sichtbarkeit des neuen Repositorys. Muss private, public oder internal sein. Wenn sie nicht festgelegt wurde, wird dein Repository als privat migriert. |
sourceRepositoryUrl | Die URL deines Quellrepositorys im Format https://github.com/{organization}/{repository}. |
Weitere Informationen zu den Anforderungen an personal access token findest du unter Verwalten des Zugriffs für eine Migration zwischen GitHub-Produkten.
Im nächsten Schritt verwendest du die von der startRepositoryMigration-Mutation zurückgegebene Migrations-ID, um den Migrationsstatus zu überprüfen.
Schritt 4: Überprüfen des Migrationsstatus
Um Migrationsfehler zu erkennen und sicherzustellen, dass deine Migration funktioniert, kannst du den Migrationsstatus mithilfe der Abfrage getMigration überprüfen. Du kannst auch den Status mehrerer Migrationsvorgänge mit getMigrations überprüfen.
Die Abfrage getMigration gibt für die Migration einen der folgenden Status zurück: queued, in progress, failed oder completed. Wenn die Migration fehlerhaft war, gibt der Importer einen Grund für den Fehler an.
Abfrage getMigration
query (
$id: ID!
){
node( id: $id ) {
... on Migration {
id
sourceUrl
migrationSource {
name
}
state
failureReason
}
}
}
| Abfragevariable | Beschreibung |
|---|---|
id | Die id deiner Migration, die von der startRepositoryMigration-Mutation zurückgegeben wurde. |
Schritt 5: Überprüfen der Migration und des Fehlerprotokolls
Um die Migration abzuschließen, solltest du das Issue „Migrationsprotokoll“ überprüfen. Dieses Problem wird in GitHub im Zielrepository erstellt.
Abschließend wird empfohlen, die Integrität deiner migrierten Repositorys zu überprüfen.
Schritt 1: Installieren der GEI extension of the GitHub CLI
Wenn dies deine erste Migration ist, musst du die GEI extension of the GitHub CLI installieren. Weitere Informationen zur GitHub CLI findest du unter Informationen zur GitHub CLI.
Alternativ können Sie eine eigenständige Binärdatei von der Veröffentlichungsseite für das github/gh-gei-Repository herunterladen. Sie können daraufhin die Binärdatei direkt ohne das gh-Präfix ausführen.
-
Installiere die GitHub CLI. Installationsanweisungen für GitHub CLI findest du im GitHub CLI-Repository.
Hinweis: Du benötigst Version 2.4.0 oder höher der GitHub CLI. Die installierte Version kannst du mit dem Befehl
gh --versionermitteln. -
Installiere die GEI extension.
Shell gh extension install github/gh-gei
gh extension install github/gh-gei
Wenn du Hilfe zur GEI extension benötigst, kannst du immer das Flag --help mit einem Befehl verwenden. Mit gh gei --help listest du z. B. alle verfügbaren Befehle auf, und mit gh gei migrate-repo --help zeigst du alle Optionen an, die für den Befehl migrate-repo verfügbar sind.
Schritt 2: Aktualisieren der GEI extension of the GitHub CLI
Die GEI extension wird wöchentlich aktualisiert. Aktualisieren die Erweiterung, um sicherzustellen, dass du die neueste Version verwendest.
gh extension upgrade github/gh-gei
Schritt 3: Festlegen der Umgebungsvariablen
Bevor du GEI extension zum Migrieren zu GitHub Enterprise Cloud verwenden kannst, musst du personal access token erstellen, die auf die Quell- und Zielorganisationen zugreifen können, und dann die personal access token als Umgebungsvariablen festlegen.
-
Erstelle ein personal access token (classic) für die Authentifizierung der Zielorganisation auf GitHub Enterprise Cloud, und stelle sicher, dass das Token alle Anforderungen erfüllt. Weitere Informationen findest du unter Verwalten des Zugriffs für eine Migration zwischen GitHub-Produkten.
-
Erstelle ein personal access token für die Authentifizierung der Quellorganisation, und stelle außerdem sicher, dass dieses Token alle Anforderungen erfüllt.
-
Lege Umgebungsvariablen für die personal access token fest, und ersetze in den folgenden Befehlen TOKEN durch die personal access token, die du oben gespeichert hast. Verwende das
GH_PATfür die Zielorganisation und dasGH_SOURCE_PATfür die Quellorganisation.-
Wenn du ein Terminal verwendest, führe den Befehl
exportaus.Shell export GH_PAT="TOKEN" export GH_SOURCE_PAT="TOKEN"
export GH_PAT="TOKEN" export GH_SOURCE_PAT="TOKEN" -
Wenn du PowerShell verwendest, führe den Befehl
$envaus.Shell $env:GH_PAT="TOKEN" $env:GH_SOURCE_PAT="TOKEN"
$env:GH_PAT="TOKEN" $env:GH_SOURCE_PAT="TOKEN"
-
Schritt 4: Generieren eines Migrationsskripts
Wenn du mehrere Repositorys gleichzeitig zu GitHub Enterprise Cloud migrieren möchtest, verwendest du die GitHub CLI, um ein Migrationsskript zu generieren. Das resultierende Skript enthält eine Liste von Migrationsbefehlen (einen pro Repository).
Hinweis: Beim Generieren eines Skripts wird ein PowerShell-Skript ausgegeben. Wenn du ein Terminal verwendest, musst du das Skript mit der Erweiterung .ps1 ausgeben und PowerShell für Mac oder Linux installieren, um es auszuführen.
Wenn du ein einzelnes Repository migrieren möchtest, fahre mit dem nächsten Schritt fort.
Generieren eines Migrationsskripts
Führe den Befehl gh gei generate-script aus, um ein Migrationsskript zu generieren.
gh gei generate-script --github-source-org SOURCE --github-target-org DESTINATION --output FILENAME
gh gei generate-script --github-source-org SOURCE --github-target-org DESTINATION --output FILENAME
Wenn das Skript das Migrationsprotokoll für jedes migrierte Repository herunterladen soll, fügst du das Flag --download-migration-logs hinzu. Weitere Informationen zu Migrationsprotokollen findest du unter Zugreifen auf die Migrationsprotokolle für GitHub Enterprise Importer.
Ersetze die Platzhalter im obigen Befehl durch die folgenden Werte.
| Platzhalter | Wert |
|---|---|
| SOURCE | Name der Ursprungsorganisation |
| DESTINATION | Name der Zielorganisation |
| FILENAME | Ein Dateiname für das resultierende Migrationsskript Wenn du das Terminal verwendest, legst du als Erweiterung .ps1 fest, da für das generierte Skript PowerShell ausgeführt werden muss. Du kannst PowerShell für Mac oder Linux installieren. |
Wenn Sie GEI als eigenständige Binärdatei heruntergeladen haben und nicht als Erweiterung für die GitHub CLI, müssen Sie das generierte Skript aktualisieren, um die Binärdatei anstelle von gh gei auszuführen.
Überprüfen des Migrationsskripts
Nachdem du das Skript generiert hast, überprüfst du die Datei, und bearbeitest ggf. das Skript.
- Wenn du einige Repositorys nicht migrieren möchtest, kannst du die entsprechenden Zeilen löschen oder auskommentieren.
- Wenn Repositorys in der Zielorganisation einen anderen Namen erhalten sollen, aktualisiere den Wert für das entsprechende Flag
--target-repo. - Wenn Sie die Sichtbarkeit des neuen Repositorys ändern möchten, aktualisieren Sie den Wert für das entsprechende Flag
--target-repo-visibility. Standardmäßig legt das Skript die gleiche Sichtbarkeit wie für das Quellrepository fest.
Hinweis: Wenn dein Repository mehr als 10 GB Releasedaten enthält, können Releases nicht migriert werden. Verwende das Flag --skip-releases, um das Repository ohne Releases zu migrieren.
Wenn Sie GEI als eigenständige Binärdatei heruntergeladen haben und nicht als Erweiterung für die GitHub CLI, müssen Sie das generierte Skript aktualisieren, um die Binärdatei anstelle von gh gei auszuführen.
Schritt 5: Migrieren von Repositorys
Mit dem Befehl gh gei migrate-repo kannst mehrere Repositorys mit einem Migrationsskript oder einem einzelnen Repository migrieren.
Migrieren mehrerer Repositorys
Führe das oben generierte Skript aus, um mehrere Repositorys zu migrieren. Ersetze FILENAME in den folgenden Befehlen durch den Dateinamen, den du beim Generieren des Skripts angegeben hast.
-
Wenn du ein Terminal verwendest, gibst du
./ein.Shell ./FILENAME
./FILENAME -
Wenn du PowerShell verwendest, gibst du
.\ein.Shell .\FILENAME
.\FILENAME
Migrieren eines einzelnen Repositorys
Verwende den Befehl gh gei migrate-repo, um ein einzelnes Repository zu migrieren.
gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME
gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME
Hinweis: Wenn dein Repository mehr als 10 GB Releasedaten enthält, können Releases nicht migriert werden. Verwende das Flag --skip-releases, um das Repository ohne Releases zu migrieren.
Ersetze die Platzhalter im obigen Befehl durch die folgenden Werte.
| Platzhalter | Wert |
|---|---|
| SOURCE | Name der Ursprungsorganisation |
| CURRENT-NAME | Der Name des Repositorys, das du migrieren möchtest |
| DESTINATION | Name der Zielorganisation |
| NEW-NAME | Der Name für das migrierte Repository |
Wenn Sie eine Migration abbrechen möchten, verwenden Sie den Befehl abort-migration und ersetzen Sie die MIGRATIONS-ID durch die zurückgesendete ID migrate-repo.
gh gei abort-migration --migration-id MIGRATION-ID
gh gei abort-migration --migration-id MIGRATION-ID
Schritt 6: Überprüfen der Migration und des Fehlerprotokolls
Nachdem die Migration abgeschlossen ist, solltest du das Migrationsprotokoll überprüfen. Weitere Informationen findest du unter Zugreifen auf die Migrationsprotokolle für GitHub Enterprise Importer.
Es wird empfohlen, die Integrität deiner migrierten Repositorys zu überprüfen.