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. Mehr über die ersten Schritte mit den APIs von GitHub erfahren Sie in Erste Schritte mit der REST-API und Erstellen von Aufrufen mit GraphQL.

Um Ihre Repositorys von GitHub Enterprise Server zu GitHub Enterprise Cloud mithilfe der APIs zu migrieren, gehen Sie wie folgt vor:

1. Erstellen Sie eine personal access token für die Quell- und die Zielorganisation
2. Rufen Sie die ownerId der Zielorganisation in GitHub Enterprise Cloud ab.
3. Richten Sie eine Migrationsquelle über GitHubdie GraphQL-API ein, um zu ermitteln, von wo Sie migrieren möchten.
4. Wiederhole diese Schritte für jedes Repository, das du migrieren möchtest.
   • Verwenden Sie die REST-API auf deine GitHub Enterprise Server-Instanz, um Migrationsarchive für Ihr Repository zu generieren.
   • Laden Sie Ihre Migrationsarchive an einen Speicherort hoch, an dem auf sie zugegriffen werden kann. GitHub
   • 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 Sie Ihre 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

Bei der Durchführung einer Migration eines Repositorys müssen Sie die Daten Ihres Repositorys 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 Ihre GitHub Enterprise Server Instanz hinter einer Firewall befindet, müssen Sie möglicherweise Blob-Speicher mit einem externen Clouddienst einrichten.

Du musst zunächst Blobspeicher bei einem unterstützten Anbieter einrichten. Wenn Sie einen Cloudanbieter verwenden, müssen Sie dann Ihre Zugangsdaten beim Speicheranbieter im Verwaltungskonsole oder 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 im 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.

Ihre Migrationsquelle ist Ihre Organisation auf 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
    }
  }
}

| url | Die URL für deine GitHub Enterprise Server-Instanz. Diese URL muss von GitHub Enterprise Cloud aus nicht zugänglich sein.

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 auf deine GitHub Enterprise Server-Instanz

Sie verwenden die REST-API, um zwei "Migrationen" zu GitHub Enterprise Serverstarten: eine, um ein Archiv der Git-Quelle Ihres Repositorys zu generieren, und eine, um ein Archiv der Metadaten Ihres Repositorys zu generieren (z. B. Probleme und Pullanforderungen).

Um das Git-Quellarchiv zu erzeugen, senden Sie eine POST-Anfrage an https://HOSTNAME/api/v3/orgs/ORGANIZATION/migrations, wobei Sie HOSTNAME durch den Hostnamen von deine GitHub Enterprise Server-Instanz und ORGANIZATION durch den Login Ihrer Organisation ersetzen.

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 für jedes Repository beide Archive (Git-Quelle und Metadaten) von Ihrem Computer an GitHub übertragen, indem Sie unsere GraphQL-API verwenden.

Wenn Sie GitHub Enterprise Server in Version 3.7 oder älter verwenden, müssen Sie zunächst URLs für die Archive erstellen, die für GitHub zugänglich sind. 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 Sie 3.8 oder höher verwenden GitHub Enterprise Server , lädt Ihre Instanz die Archive hoch und generiert die URLs für Sie. Der Location-Header im vorherigen Schritt enthält die kurzlebige URL.

Möglicherweise müssen Sie die IP-Bereiche von GitHub zur Allowlist hinzufügen. Weitere Informationen finden Sie unter Verwalten des Zugriffs für eine Migration zwischen GitHub-Produkten.

Hochladen Ihrer Migrationsarchive auf GitHub-owned blob storage

Wenn Sie GitHub-owned blob storage verwenden, laden Sie Ihr Archiv mithilfe des folgenden Verfahrens auf 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
    }
  }
}

gitArchiveUrl | Eine GitHub Enterprise CloudURL mit Zugriff auf Ihr Git-Quellarchiv.

metadataArchiveUrl | Eine GitHub Enterprise Cloudbarrierefreie URL für Ihr Metadatenarchiv.

sourceRepositoryUrl | Die URL für Ihr Repository in Ihrer GitHub Enterprise Server Instanz. Dies ist erforderlich, kommuniziert aber GitHub Enterprise Cloud nicht direkt mit Ihrer GitHub Enterprise Server Instanz.

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