Migrieren von Repositorys von Azure DevOps zu GitHub Enterprise Cloud

Du kannst Repositorys von Azure DevOps zu GitHub Enterprise Cloud migrieren, indem du die GitHub CLI oder die GraphQL-API verwendest.

Tool navigation

In diesem Artikel

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.

Um Anweisungen für die Verwendung der API anzuzeigen, verwendest du den Toolumschalter oben auf der Seite.
Um Anweisungen zur Verwendung der GitHub CLI anzuzeigen, verwendest du den Toolumschalter oben auf der Seite.

Voraussetzungen

  • Es wird dringend empfohlen, einen Testlauf deiner Migration durchzuführen und die Produktionsmigration bald danach abzuschließen. Weitere Informationen zu Testläufen findest du unter Übersicht über die Migration von Azure DevOps zu GitHub Enterprise Cloud.
  • Stellen Sie sicher, dass Sie die zu migrierenden Daten und die bekannten Supportbeschränkungen des Importer verstehen. Weitere Informationen findest du unter Informationen zu Migrationen von Azure DevOps zu GitHub Enterprise Cloud.
  • 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.
  • Für die Zielorganisation auf GitHub müssen Sie Inhaber des Unternehmens sein oder die Rolle des Migrationsbeauftragten haben. Weitere Informationen zur Migrationsrolle findest du unter Verwalten des Zugriffs für eine Migration von Azure DevOps.

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.

Du sendest alle GraphQL-Abfragen an das Ziel deiner Migration. Stelle bei der Migration zu GitHub Enterprise-Cloud mit Datenresidenz sicher, dass du Abfragen an den Endpunkt für die Unterdomäne für GHE.com sendest.

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
  }
}
AbfragevariableBeschreibung
loginName 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 deine ADO-Organisation.

createMigrationSource-Mutation

mutation createMigrationSource($name: String!, $ownerId: ID!) {
  createMigrationSource(input: {name: $name, url: "https://dev.azure.com", ownerId: $ownerId, type: AZURE_DEVOPS}) {
    migrationSource {
      id
      name
      url
      type
    }
  }
}

Note

Stelle sicher, dass du AZURE_DEVOPS für type verwendest.

AbfragevariableBeschreibung
nameEin Name für deine Migrationsquelle. Dieser Name dient deiner eigenen Referenz, sodass du eine beliebige Zeichenfolge angeben kannst.
ownerIdDie Organisations-ID deiner Organisation in GitHub Enterprise Cloud.

Antwort von createMigrationSource

{
  "data": {
    "createMigrationSource": {
      "migrationSource": {
        "id": "MS_kgDaACQxYmYxOWU4Yi0wNzZmLTQ3NTMtOTdkZC1hNGUzZmYxN2U2YzA",
        "name": "Azure Devops Source",
        "url": "https://dev.azure.com",
        "type": "AZURE_DEVOPS"
      }
    }
  }
}

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
    }
  }
}
AbfragevariableBeschreibung
sourceIdDie id deiner Migrationsquelle, die von der createMigrationSource-Mutation zurückgegeben wurde.
ownerIdDie Organisations-ID deiner Organisation in GitHub Enterprise Cloud.
repositoryNameEin 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.
continueOnErrorMigrationseinstellung, 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.
githubPatDas personal access token für deine Zielorganisation auf GitHub Enterprise Cloud.
accessTokenDas personal access token für deine Quelle.
targetRepoVisibilityDie Sichtbarkeit des neuen Repositorys. Muss private, public oder internal sein. Wenn sie nicht festgelegt wurde, wird dein Repository als privat migriert.
sourceRepositoryUrlDie URL deines Quellrepositorys im Format https://dev.azure.com/{organization}/{project}/_git/{repository}.

Weitere Informationen zu den Anforderungen für personal access token findest du unter Verwalten des Zugriffs für eine Migration von Azure DevOps.

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
    }
  }
}
AbfragevariableBeschreibung
idDie 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.

Screenshot eines Problems mit dem Titel „Migrationsprotokoll“. Der zweite Kommentar im Issue enthält Protokolle für eine Migration.

Abschließend wird empfohlen, die Integrität deiner migrierten Repositorys zu überprüfen.

Schritt 1: Installieren der ADO2GH extension of the GitHub CLI

Wenn dies deine erste Migration ist, musst du die ADO2GH 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-ado2gh-Repository herunterladen. Sie können diese Binärdatei direkt ohne das gh-Präfix ausführen.

  1. Installiere die GitHub CLI. Installationsanweisungen für GitHub CLI findest du im GitHub CLI-Repository.

    Note

    Du benötigst Version 2.4.0 oder höher der GitHub CLI. Die installierte Version kannst du mit dem Befehl gh --version ermitteln.

  2. Installiere die ADO2GH extension.

    Shell
    gh extension install github/gh-ado2gh

Wenn du Hilfe zur ADO2GH extension benötigst, kannst du immer das Flag --help mit einem Befehl verwenden. Mit gh ado2gh --help listest du z. B. alle verfügbaren Befehle auf, und mit gh ado2gh migrate-repo --help zeigst du alle Optionen an, die für den Befehl migrate-repo verfügbar sind.

Schritt 2: Aktualisieren der ADO2GH extension of the GitHub CLI

Die ADO2GH extension of the GitHub CLI wird wöchentlich aktualisiert. Aktualisieren die Erweiterung, um sicherzustellen, dass du die neueste Version verwendest.

Shell
gh extension upgrade github/gh-ado2gh

Schritt 3: Festlegen der Umgebungsvariablen

Bevor du die ADO2GH 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.

  1. 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 finden Sie unter Verwalten des Zugriffs für eine Migration von Azure DevOps.

  2. Erstelle ein personal access token für die Authentifizierung der Quellorganisation in Azure DevOps, und stelle sicher, dass dieses Token alle Anforderungen erfüllt. Weitere Informationen finden Sie unter Verwalten des Zugriffs für eine Migration von Azure DevOps.

  3. 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_PAT für die Zielorganisation und das ADO_PAT für die Quellorganisation.

    • Wenn du ein Terminal verwendest, führe den Befehl export aus.

      Shell
      export GH_PAT="TOKEN"
export ADO_PAT="TOKEN"

    • Wenn du PowerShell verwendest, führe den Befehl $env aus.

      Shell
      $env:GH_PAT="TOKEN"
$env:ADO_PAT="TOKEN"

  4. Lege bei der Migration zu GitHub Enterprise-Cloud mit Datenresidenz der Einfachheit halber eine Umgebungsvariable für die Basis-API-URL für dein Unternehmen fest. Zum Beispiel:

    Shell
    export TARGET_API_URL="https://api.octocorp.ghe.com"

    Du verwendest diese Variable mit der Option --target-api-url in Befehlen, die du mit der GitHub CLI ausführst.

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).

Note

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 ado2gh generate-script aus, um ein Migrationsskript zu generieren.

Shell
gh ado2gh generate-script --ado-org SOURCE --github-org DESTINATION --output FILENAME

Platzhalter

Ersetze die Platzhalter im obigen Befehl durch die folgenden Werte.

PlatzhalterWert
SOURCEName der Ursprungsorganisation
DESTINATIONName der Zielorganisation
FILENAMEEin 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.

Zusätzliche Argumente

ArgumentBeschreibung
--target-api-url TARGET-API-URLWenn du zu GHE.com migrierst, füge --target-api-url TARGET-API-URL hinzu, wobei TARGET-API-URL die Basis-API-URL für die Unterdomäne deines Unternehmens ist. Beispiel: https://api.octocorp.ghe.com
--allFüge dem Skript zusätzliche Funktionen hinzu, z. B. das erneute Verknüpfen von Pipelines, Erstellen von Teams und Konfigurieren von Azure Boards-Integrationen.
--download-migration-logsÜberprüfe das Migrationsprotokoll für jedes migrierte Repository. Weitere Informationen zu Migrationsprotokollen findest du unter Zugreifen auf die Migrationsprotokolle für GitHub Enterprise Importer.

Ü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.

Wenn Sie ADO2GH 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 ado2gh auszuführen.

Schritt 5: Migrieren von Repositorys

Mit dem Befehl gh ado2gh 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

  • Wenn du PowerShell verwendest, gibst du .\ ein.

    Shell
    .\FILENAME

Migrieren eines einzelnen Repositorys

Verwende den Befehl gh ado2gh migrate-repo, um ein einzelnes Repository zu migrieren.

Shell
gh ado2gh migrate-repo --ado-org SOURCE --ado-team-project TEAM-PROJECT --ado-repo CURRENT-NAME --github-org DESTINATION --github-repo NEW-NAME

Note

Wenn du zu GHE.com migrierst, füge --target-api-url TARGET-API-URL hinzu, wobei TARGET-API-URL die Basis-API-URL für die Unterdomäne deines Unternehmens ist. Beispiel: https://api.octocorp.ghe.com

Ersetze die Platzhalter im obigen Befehl durch die folgenden Werte.

PlatzhalterWert
SOURCEName der Ursprungsorganisation
CURRENT-NAMEDer Name des Repositorys, das du migrieren möchtest
DESTINATIONName der Zielorganisation
NEW-NAMEDer Name für das migrierte Repository
TEAMPROJEKTName des Teamprojekts des Repositorys, das du migrieren möchtest

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.

Shell
gh ado2gh 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.