Migrieren von Repositorys von GitHub Enterprise Server zu GitHub Enterprise Cloud

Du kannst Repositorys von GitHub Enterprise Server zu GitHub Enterprise Cloud migrieren, indem du die GitHub CLI oder die 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.

Wenn du die API verwendest, musst du eigene Skripts schreiben oder einen HTTP-Client wie Insomnia verwenden. Weitere Informationen zu den ersten Schritten mit den APIs von GitHub findest du unter Erste Schritte mit der REST-API und Erstellen von Aufrufen mit GraphQL.

Wenn du deine Repositorys mit den APIs von GitHub Enterprise Server zu GitHub Enterprise Cloud migrieren möchten, gehst du wie folgt vor:

  1. Erstellen eines personal access token für die Quell- und die Zielorganisation
  2. Abrufen der ownerId der Zielorganisation in GitHub Enterprise Cloud
  3. Einrichten einer Migrationsquelle über die GraphQL-API von GitHub zur Angabe des Ausgangspunkts der Migration
  4. Wiederhole diese Schritte für jedes Repository, das du migrieren möchtest.
    • Verwenden der REST-API in deine GitHub Enterprise Server-Instanz zum Generieren von Migrationsarchiven für dein Repository
    • Hochladen von Migrationsarchiven an einen Speicherort, an dem GitHub darauf zugreifen kann
    • Starte deine Migration mit der GraphQL-API für dein Migrationsziel, und übergib deine Archiv-URLs.
    • Überprüfen des Status deiner Migration über die GraphQL-API
    • Überprüfen der Migration und des Fehlerprotokolls

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 zwischen GitHub-Produkten.
  • 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 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 finden Sie unter Verwalten des Zugriffs für eine Migration zwischen GitHub-Produkten.
  • Wenn Sie Blob Storage für exportierte Archive mit GitHub Enterprise Server 3.8 oder höher konfigurieren, benötigen Sie Zugriff auf die Verwaltungskonsole.

Schritt 1: Erstellen deines personal access token

  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 zwischen GitHub-Produkten.
  2. Erstelle ein personal access token für die Authentifizierung der Quellorganisation, und stelle außerdem sicher, dass dieses Token alle Anforderungen erfüllt.

Schritt 2: Abrufen der ownerId für die Zielorganisation

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 3: Einrichten des Blobspeichers

Da sich viele GitHub Enterprise Server-Instanzen hinter Firewalls befinden, verwendest du für Versionen von GitHub Enterprise Server ab 3.8 Blobspeicher als Zwischenspeicherort für deine Daten, auf den GitHub Zugriff hat.

Du musst den Blobspeicher zunächst bei einem unterstützten Cloudanbieter einrichten und dann deine Einstellungen an der Verwaltungskonsole von deine GitHub Enterprise Server-Instanz konfigurieren.

Note

Du musst Blob Storage nur dann konfigurieren, wenn du GitHub Enterprise Server 3.8 oder höher verwendest. Wenn du GitHub Enterprise Server 3.7 oder niedriger verwendest, fahre mit Schritt 4: Einrichten einer Migrationsquelle in GitHub Enterprise Cloud fort.

Blobspeicher ist erforderlich, um Repositorys mit einer großen Git-Quelle oder umfangreichen Metadaten zu migrieren. Wenn du GitHub Enterprise Server 3.7 oder niedriger verwendest, kannst du keine Migrationsvorgänge durchführen, bei denen die Git-Quelle oder die Metadatenexporte 2 GB übersteigen. Um solche Migrationsvorgänge durchzuführen, führst du ein Update auf GitHub Enterprise Server 3.8 oder höher durch.

Einrichten von Blobspeicher bei einem unterstützten Cloudanbieter

Die GitHub CLI unterstützt die folgenden Blobspeicheranbieter:

  • Amazon Web Services S3 (AWS)
  • Azure Blob Storage

Einrichten eines AWS S3-Speicherbuckets

Richte in AWS einen S3-Bucket ein. Weitere Informationen findest du unter Erstellen von Buckets in der AWS-Dokumentation.

Außerdem benötigst du einen AWS-Zugriffsschlüssel und einen geheimen Schlüssel mit den folgenden Berechtigungen:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:ListBucketMultipartUploads",
                "s3:AbortMultipartUpload",
                "s3:ListBucket",
                "s3:DeleteObject",
                "s3:ListMultipartUploadParts"
            ],
            "Resource": [
                "arn:aws:s3:::github-migration-bucket",
                "arn:aws:s3:::github-migration-bucket/*"
            ]
        }
    ]
}

Note

GitHub Enterprise Importer löscht dein Archiv nach Abschluss der Migration nicht aus AWS. Zur Verringerung der Speicherkosten wird empfohlen, das automatische Löschen deines Archivs nach einem bestimmten Zeitraum zu konfigurieren. Weitere Informationen findest du unter Festlegen der Lebenszykluskonfiguration für einen Bucket in der AWS-Dokumentation.

Einrichten eines Azure Blob Storage-Kontos

Erstelle in Azure ein Speicherkonto, und notiere dir die Verbindungszeichenfolge. Weitere Informationen findest du unter Verwalten von Speicherkonto-Zugriffsschlüsseln in der Microsoft-Dokumentation.

Note

GitHub Enterprise Importer löscht dein Archiv nach Abschluss der Migration nicht aus Azure Blob Storage. Zur Verringerung der Speicherkosten wird empfohlen, das automatische Löschen deines Archivs nach einem bestimmten Zeitraum zu konfigurieren. Weitere Informationen findest du unter Optimieren von Kosten durch automatisches Verwalten des Datenlebenszyklus in der Microsoft-Dokumentation.

Konfigurieren von Blobspeicher an der Verwaltungskonsole von deine GitHub Enterprise Server-Instanz

Nachdem du einen AWS S3-Speicherbucket oder ein Azure Blob Storage-Speicherkonto eingerichtet hast, konfigurierst du den Blobspeicher an der Verwaltungskonsole von deine GitHub Enterprise Server-Instanz. Weitere Informationen zur Verwaltungskonsole findest du unter Verwalten von Instanzen über die Verwaltungskonsole.

  1. Klicke in einem Verwaltungskonto für GitHub Enterprise Server in der rechten oberen Ecke einer beliebigen Seite auf .

  2. Wenn du dich nicht bereits auf der Seite „Websiteadministrator“ befindest, klicke in der oberen linken Ecke auf Websiteadministrator. 1. Wähle auf der Randleiste „ Websiteadministrator“ die Option Verwaltungskonsole aus.

  3. Melde dich an der Verwaltungskonsole an.

  4. Wähle auf der oberen Navigationsleiste Einstellungen aus.

  5. Wähle unter Migrationen die Option GitHub-Migrationen aktivieren aus.

  6. Wähle optional zum Importieren von Speichereinstellungen, die du für GitHub Actions konfiguriert hast, die Option Speichereinstellungen aus Actions kopieren aus. Weitere Informationen findest du unter Aktivieren von GitHub Actions mit Azure Blob Storage und Aktivieren von GitHub Actions mit Amazon S3-Speicher.

    Note

    Nach dem Kopieren deiner Speichereinstellungen musst du möglicherweise die Konfiguration deines Cloud-Speicherkontos aktualisieren, um mit GitHub Enterprise Importer zu arbeiten. Insbesondere müssen Sie sicherstellen, dass die IP-Adressen von GitHub zugelassen sind. Weitere Informationen finden Sie unter Verwalten des Zugriffs für eine Migration zwischen GitHub-Produkten.

  7. Wenn du keine Speichereinstellungen aus GitHub Actions importierst, wähle entweder Azure Blob Storage oder Amazon S3 aus, und gib die erforderlichen Details ein.

    Note

    Bei Verwendung von Amazon S3 muss die „AWS Service-URL“ auf den Standard-Endpunkt für die AWS-Region festgelegt werden, in der sich der Bucket befindet. Wenn sich der Bucket beispielsweise in der Region eu-west-1 befindet, lautet die „AWS Service-URL“ https://s3.eu-west-1.amazonaws.com . Das Netzwerk Ihrer GitHub Enterprise Server-Instanz muss den Zugriff auf diesen Host zulassen. Gateway-Endpunkte werden nicht unterstützt, wie z. B. bucket.vpce-0e25b8cdd720f900e-argc85vg.s3.eu-west-1.vpce.amazonaws.com. Weitere Informationen zu Gateway-Endpunkten finden Sie in der AWS-Dokumentation unter Gateway-Endpunkte für Amazon S3.

  8. Wähle Speichereinstellungen testen aus.

  9. Klicke auf Save settings (Einstellungen speichern).

Zulassen des Netzwerkzugriffs

Wenn du Firewallregeln für dein Speicherkonto konfiguriert hast, musst du sicherstellen, dass du Zugriff auf die IP-Adressbereiche für dein Migrationsziel hast. Weitere Informationen findest du unter Verwalten des Zugriffs für eine Migration zwischen GitHub-Produkten.

Schritt 4: Einrichten einer Migrationsquelle in GitHub Enterprise Cloud

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.

Die Migrationsquelle ist deine Organisation in GitHub Enterprise Server.

createMigrationSource-Mutation

mutation createMigrationSource($name: String!, $url: String!, $ownerId: ID!) {
  createMigrationSource(input: {name: $name, url: $url, ownerId: $ownerId, type: GITHUB_ARCHIVE}) {
    migrationSource {
      id
      name
      url
      type
    }
  }
}

Note

Stelle sicher, dass du GITHUB_ARCHIVE 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.
urlURL für deine GitHub Enterprise Server-Instanz. Auf diese URL muss nicht über GitHub Enterprise Cloud zugegriffen werden können.

Antwort von createMigrationSource

{
  "data": {
    "createMigrationSource": {
      "migrationSource": {
        "id": "MS_kgDaACRjZTY5NGQ1OC1mNDkyLTQ2NjgtOGE1NS00MGUxYTdlZmQwNWQ",
        "name": "GHES Source",
        "url": "https://my-ghes-hostname.com",
        "type": "GITHUB_ARCHIVE"
      }
    }
  }
}

In diesem Beispiel ist MS_kgDaACRjZTY5NGQ1OC1mNDkyLTQ2NjgtOGE1NS00MGUxYTdlZmQwNWQ die ID der Migrationsquelle, die du in einem späteren Schritt verwendest.

Schritt 5: Generieren von Migrationsarchiven in deine GitHub Enterprise Server-Instanz

Du verwendest die REST-API, um in GitHub Enterprise Server zwei „Migrationsvorgänge“ zu starten: einen zum Generieren eines Archivs der Git-Quelle deines Repositorys und einen zum Generieren eines Archivs der Metadaten deines Repositorys (z. B. Issues und Pull Requests).

Um das Git-Quellarchiv zu generieren, übermittelst du eine POST-Anforderung an https://HOSTNAME/api/v3/orgs/ORGANIZATION/migrations, und ersetzt dabei HOSTNAME durch den Hostnamen von deine GitHub Enterprise Server-Instanz und ORGANIZATION durch die Anmeldung deiner Organisation.

Gib im Text das Repository an, das du migrieren möchtest. Deine Anforderung sieht ungefähr wie folgt aus:

POST /api/v3/orgs/acme-corp/migrations HTTP/1.1
Accept: application/vnd.github+json
Authorization: Bearer <TOKEN>
Content-Type: application/json
Host: github.acmecorp.net

{
  "repositories": ["repository_to_migrate"],
  "exclude_metadata": true
}

Um dein Metadatenarchiv zu generieren, übermittelst du eine ähnliche Anforderung mit dem folgenden Text an dieselbe URL:

{
  "repositories": ["repository_to_migrate"],
  "exclude_git_data": true,
  "exclude_releases": false,
  "exclude_owner_projects": true
}

Beide API-Aufrufe geben eine JSON-Antwort zurück, die auch die ID der gestarteten Migration enthält.

HTTP/1.1 201 Created

{
  "id": 123,
  // ...
}

Weitere Informationen findest du unter Initiieren einer Organisationsmigration.

Das Generieren der Archive kann je nach Datenmenge eine Weile dauern. Du kannst den Status der beiden Migrationsvorgänge regelmäßig mit der API „Migrationsstatus einer Organisation abrufen“ überprüfen, bis sich der state der Migration in exported ändert.

GET /api/v3/orgs/acme-corp/migrations/123 HTTP/1.1
Accept: application/vnd.github+json
Authorization: Bearer <TOKEN>
Host: github.acmecorp.net

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 123,
  "state": "exported",
  // ...
}

Weitere Informationen findest du unter Abrufen des Migrationsstatus einer Organisation.

Note

Wenn deine Migration in den Zustand failed und nicht in den Zustand exported wechselt, solltest du versuchen, die Migration erneut zu starten. Wenn die Migration wiederholt zu Fehlern führt, wird empfohlen, die Archive mit ghe-migrator anstelle der API zu generieren.

Führe die Schritte unter Exportieren von Migrationsdaten aus deinem Unternehmen aus, und füge der Migration nur ein Repository hinzu. Am Ende des Prozesses verfügst du über ein einzelnes Migrationsarchiv mit deiner Git-Quelle und den Metadaten kannst mit Schritt 6 in diesem Artikel fortfahren.

Nachdem der state einer Migration in exported geändert wurde, kannst du die URL der Migration mithilfe der API „Organisationsmigrationsarchiv herunterladen“ abrufen.

GET /api/v3/orgs/acme-corp/migrations/123/archive HTTP/1.1
Accept: application/vnd.github+json
Authorization: Bearer <TOKEN>
Host: github.acmecorp.net

HTTP/1.1 302 Found
Location: https://media.github.acmecorp.net/migrations/123/archive/cca2ebe9-7403-4ffa-9b6a-4c9e16c94410?token=AAAAABEWE7JP4H2HACKEGMTDOYRC6

Die API gibt als Antwort 302 Found mit einem Location-Header zurück, der auf die URL umleitet, unter der sich das herunterladbare Archiv befindet. Lade die beiden Dateien herunter: eine für die Git-Quelle und eine für die Metadaten.

Weitere Informationen findest du unter Herunterladen eines Organisationsmigrationsarchivs.

Nachdem beide Migrationsvorgänge abgeschlossen sind und du die Archive heruntergeladen hast, kannst du mit dem nächsten Schritt fortfahren.

Schritt 6: Hochladen deiner Migrationsarchive

Um die Daten in GitHub Enterprise Cloud zu importieren, müssen Sie beide Archive für jedes Repository (Git-Quelle und Metadaten) über die GraphQL-API von Ihrem Computer an GitHub übergeben.

Wenn Sie GitHub Enterprise Server 3.7 oder niedriger verwenden, müssen Sie zuvor URLs für die Archive generieren, auf die GitHub zugreifen kann. Die meisten Kund*innen entscheiden sich dafür, die Archive in den Blobspeicherdienst eines Cloudanbieters wie Amazon S3 oder Azure Blob Storage hochzuladen und dann eine kurzlebige URL für jedes Objekt zu generieren.

Wenn du GitHub Enterprise Server 3.8 oder höher verwendest, lädt deine Instanz die Archive hoch und generiert die URLs für dich. Der Location-Header im vorherigen Schritt enthält die kurzlebige URL.

Möglicherweise musst du die IP-Bereiche von GitHub auf die Positivliste setzen. Weitere Informationen finden Sie unter Verwalten des Zugriffs für eine Migration zwischen GitHub-Produkten.

Schritt 7: 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!,
  $repositoryName: String!,
  $continueOnError: Boolean!,
  $accessToken: String!,
  $githubPat: String!,
  $gitArchiveUrl: String!,
  $metadataArchiveUrl: String!,
  $sourceRepositoryUrl: URI!,
  $targetRepoVisibility: String!
){
  startRepositoryMigration( input: {
    sourceId: $sourceId,
    ownerId: $ownerId,
    repositoryName: $repositoryName,
    continueOnError: $continueOnError,
    accessToken: $accessToken,
    githubPat: $githubPat,
    targetRepoVisibility: $targetRepoVisibility
    gitArchiveUrl: $gitArchiveUrl,
    metadataArchiveUrl: $metadataArchiveUrl,
    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.
gitArchiveUrlEine URL für dein Git-Quellarchiv, auf die GitHub Enterprise Cloud Zugriff hat.
metadataArchiveUrlEine URL für dein Metadatenarchiv, auf die GitHub Enterprise Cloud Zugriff hat.
sourceRepositoryUrlDie URL für das Repository auf deiner GitHub Enterprise Server-Instanz. Sie ist zwar erforderlich, aber GitHub Enterprise Cloud kommuniziert nicht direkt mit deiner GitHub Enterprise Server-Instanz.

Weitere Informationen zu den Anforderungen für 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 8: Ü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 9: Ü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.