Migrieren von Repositorys von GitHub Enterprise Server zu GitHub Enterprise Cloud

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 finden Sie 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. Richten Sie eine Migrationsquelle über die GraphQL-API von GitHub ein, um zu identifizieren, von wo aus Sie migrieren
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
   • Laden Sie Ihre Migrationsarchive an einen Ort hoch, an dem sie von GitHub aufgerufen werden können
   • Starten Sie Ihre Migration mit der GraphQL-API für Ihr Migrationsziel, und übergeben Sie Ihre 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.

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
  }
}

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

Wenn du eine Repositorymigration durchführst, musst du deine Repositorydaten an einem Ort speichern, auf den GitHub Enterprise Importer zugreifen kann. Dies kann wie folgt erreicht werden:

• Verwenden eines lokalen Speichers auf der GHES-Instanz (GHES 3.16 und höher)
• Verwenden eines Blob Storage-Anbieters

Verwenden des lokalen Speichers (GHES 3.16 und höher)

Wenn du eine Migration mit lokalem Speicher ausführst, werden Archivdaten auf den Datenträger auf deine GitHub Enterprise Server-Instanz geschrieben, ohne dass ein Cloudspeicheranbieter erforderlich ist.

• Wenn du keine Firewallregeln hast, die den ausgehenden Datenverkehr von GitHub Enterprise Server blockieren, kann GitHub Enterprise Importer das gespeicherte Archiv automatisch von GitHub Enterprise Server abrufen.
• Wenn du Firewallregeln hast und den Zugriff auf GitHub Enterprise Importer nicht zulassen möchtest, kannst du deine Archivdaten in GitHub-owned blob storage hochladen, damit GitHub Enterprise Importer darauf zugreifen kann. Informationen zur manuellen Ausführung findest du in der API-Version dieses Artikels unter Hochladen der Migrationsarchive in Blob Storage im Besitz von GitHub.

1. Klicke in einem Verwaltungskonto für GitHub Enterprise Server in der rechten oberen Ecke einer beliebigen Seite auf .
2. Klicke in der Randleiste „ Site admin“ auf Verwaltungskonsole.
3. Melde dich bei Verwaltungskonsole an.
4. Klicke auf der linken Randleiste auf Migrations.
5. Klicke auf Enable GitHub Migrations.
6. Klicke unter „Migrations Storage“ auf Local Storage.
7. Klicke auf Save settings (Einstellungen speichern).

Wenn du die Migration durchführst, überwache den Speicherplatz auf GitHub Enterprise Server. Migrationsarchive werden nach 7 Tagen automatisch gelöscht. Um Speicherplatz freizugeben, kannst du ein Archiv mithilfe von REST-API-Endpunkte für Organisationsmigrationen löschen.

Verwenden eines Blob Storage-Anbieters

Wenn sich deine GitHub Enterprise Server-Instanz hinter einer Firewall befindet, solltest du Blobspeicher mit einem externen Clouddienst einrichten.

Du musst zunächst Blobspeicher bei einem unterstützten Anbieter einrichten. Wenn du einen Cloudanbieter verwendest, musst du anschließend deine Anmeldeinformationen für den Speicheranbieter mit der Verwaltungskonsole oder der GitHub CLI konfigurieren.

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/*"
            ]
        }
    ]
}

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.

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. Klicke in der Randleiste „ Site admin“ auf Verwaltungskonsole.

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.

   Hinweis

   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.

   Hinweis

   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 Sie Firewallregeln für Ihr Speicherkonto konfiguriert haben, müssen Sie sicherstellen, dass Sie Zugriff auf die IP-Adressbereiche für Ihr Migrationsziel haben. 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
    }
  }
}

          `createMigrationSource`-Antwort:

{
  "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 finden Sie 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 finden Sie unter Abrufen des Migrationsstatus einer Organisation.

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 finden Sie 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 Ihre Daten in GitHub Enterprise Cloud zu importieren, müssen Sie beide Archive für jedes Repository (Git-Quellcode und Metadaten) von Ihrem Rechner an GitHub übergeben, indem Sie unsere GraphQL-API verwenden.

Wenn Sie GitHub Enterprise Server 3.7 oder niedriger verwenden, müssen Sie zuvor URLs für die Archive generieren, auf die GitHub. 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.

Deine Migrationsarchive werden in GitHub-owned blob storage hochgeladen.

Wenn du GitHub-owned blob storage verwendest, lade dein Archiv mithilfe des folgenden Prozesses in GitHub-owned blob storage hoch:

1. Erstellen eines mehrteiligen Uploads durch Übermitteln einer POST-Anforderung
2. Hochladen eines Archivs in mehreren Teilen mit einer Größe von bis zu 100 MB als PATCH-Anforderungen
3. Übermitteln einer PUT-Anforderung zum Abschließen des Uploads

1. Erstellen des mehrteiligen Uploads

Du sendest eine POST-Anforderung an:

https://uploads.github.com/organizations/{organization_id}/gei/archive/blobs/uploads

Füge einen JSON-Text wie unten gezeigt mit dem Archivnamen und der Größe ein. Der Inhaltstyp kann für alle Uploads unverändert "application/octet-stream" bleiben.

{
"content_type": "application/octet-stream",
"name": "git-archive.tar.gz",
"size": 262144000
}

Dadurch wird eine JSON-Objektantwort wie folgt zurückgegeben:

{
  "guid": "363b2659-b8a3-4878-bfff-eed4bcb54d35",
  "node_id": "MA_kgDaACQzNjNiMjY1OS1iOGEzLTQ4NzgtYmZmZi1lZWQ0YmNiNTRkMzU",
  "name": "git-archive.tar.gz",
  "size": 33287,
  "uri": "gei://archive/363b2659-b8a3-4878-bfff-eed4bcb54d35",
  "created_at": "2024-11-13T12:35:45.761-08:00"
}

Dieser URI stellt das hochgeladene Archiv dar und wird zum Einreihen der Migration in die Warteschlange verwendet, wenn du die Repositorymigration startest. Die Antwort enthält auch den Speicherort im Antwortheader, der zum Hochladen von Dateiteilen mithilfe einer PATCH-Anforderung im nächsten Schritt verwendet wird:

/organizations/{organization_id}/gei/archive/blobs/uploads?part_number=1&guid=<guid>&upload_id=<upload_id>

2. Hochladen des Archivs in mehreren Teilen

Lade bis zu 100 MB deiner Datei in jedem Teil mit einer PATCH-Anforderung unter Verwendung des Speicherorts aus dem vorherigen Antwortheader hoch, um sicherzustellen, dass die Rohdaten im Anforderungstext hochgeladen werden, ohne ein mehrteiliges Formular zu verwenden. Wenn der letzte Teil deiner Datei kleiner als 100 MB ist, lade nur die verbleibenden Bytes in dieser letzten Anforderung hoch:

https://uploads.github.com/{location}

Dadurch wird ein leerer Antworttext mit dem folgenden Speicherort im Antwortheader zurückgegeben:

/organizations/{organization_id}/gei/archive/blobs/uploads?part_number=2&guid=<guid>&upload_id=<upload_id>

Wiederhole diesen Vorgang, bis der Upload abgeschlossen ist. Stelle sicher, dass du bis zu 100 MB der Datei gleichzeitig einliest und Anforderungen mit den erhöhten part_number-Werten an die neuen Speicherortwerte übermittelst.

3. Abschließen des Uploads

Übermittle eine PUT-Anforderung an den Wert „letzter Pfad“ aus dem vorherigen Schritt mit einem leeren Text, und dein Upload in den GitHub-eigenen Speicher ist abgeschlossen. Der GEI-URI kann mit der GUID aus dieser anfänglichen POST-Anforderung im folgenden Format erstellt werden:

gei://archive/{guid}

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
    }
  }
}

          `metadataArchiveUrl` | Eine GitHub Enterprise Cloud-zugriffsbereite URL für Ihr Metadaten-Archiv.

          `sourceRepositoryUrl` | Die URL für das Repository auf Ihrer 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 an personal access token finden Sie 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
    }
  }
}

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.

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