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 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. 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 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 findest du 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 findest du 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.

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.

  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 GEI extension.

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

  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 findest du 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.

  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 GH_SOURCE_PAT für die Quellorganisation.

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

      Shell
      export GH_PAT="TOKEN"
export GH_SOURCE_PAT="TOKEN"

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

      Shell
      $env:GH_PAT="TOKEN"
$env:GH_SOURCE_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: Einrichten des Blobspeichers

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

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

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

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 der Anmeldeinformationen deines Blobspeichers

Nachdem du bei einem unterstützten Cloudanbieter Blobspeicher eingerichtet hast, musst du deine Anmeldeinformationen für den Speicheranbieter in GitHub konfigurieren:

  • Wenn du GitHub Enterprise Server 3.8 oder höher verwendest, konfigurierst du deine Anmeldeinformationen an der Verwaltungskonsole.
  • Wenn du GitHub Enterprise Server 3.7 oder niedriger verwendest, konfigurierst du die Anmeldeinformationen mithilfe der GitHub CLI.

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

Note

Du musst nur dann Blobspeicher an der Verwaltungskonsole konfigurieren, wenn du GitHub Enterprise Server 3.8 oder höher verwendest. Wenn du 3.7 oder niedriger verwendest, konfigurierst du deine Anmeldeinformationen stattdessen mithilfe der GitHub CLI.

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

Konfigurieren der Anmeldeinformationen für den Blobspeicher mithilfe der GitHub CLI

Note

Du musst die Anmeldeinformationen für deinen Blobspeicher nur dann mit der GitHub CLI konfigurieren, wenn du GitHub Enterprise Server 3.7 oder niedriger verwendest. Wenn du 3.8 oder höher verwendest, konfigurierst du den Blobspeicher stattdessen an der Verwaltungskonsole.

Wenn du deine Anmeldeinformationen für den Blobspeicher mithilfe der GitHub CLI konfigurierst, kannst du keine Migrationsvorgänge durchführen, bei denen die Git-Quelle oder die Metadatenexporte größer als 2 GB sind. Um solche Migrationsvorgänge durchzuführen, führst du ein Upgrade auf GitHub Enterprise Server 3.8 oder höher durch.

Konfigurieren der Anmeldeinformationen für AWS S3 mithilfe der GitHub CLI

Wenn du bereit bist, die Migration auszuführen, musst du deine AWS-Anmeldeinformationen in der GitHub CLI angeben: Region, Zugriffsschlüssel, geheimer Schlüssel und Sitzungstoken (falls erforderlich). Du kannst sie als Argumente übergeben oder die Umgebungsvariablen AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY und AWS_SESSION_TOKEN festlegen.

Du musst auch den Namen des S3-Buckets im --aws-bucket-name.Argument übergeben.

Konfigurieren der Anmeldeinformationen für Azure Blob Storage mithilfe der GitHub CLI

Wenn du bereit bist, die Migration auszuführen, kannst du deine Verbindungszeichenfolge entweder als Argument an die GitHub CLI übergeben oder mithilfe der Umgebungsvariable AZURE_STORAGE_CONNECTION_STRING übergeben.

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 5: 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

Du musst diesen Schritt von einem Computer aus ausführen, der auf die API für deine GitHub Enterprise Server-Instanz zugreifen kann. Wenn du über den Browser auf deine Instanz zugreifen kannst, hat der Computer den erforderlichen Zugriff.

Führe den Befehl gh gei generate-script aus, um ein Migrationsskript zu generieren.

Verwende für GitHub Enterprise Server 3.8 oder höher oder bei Verwendung von 3.7 oder niedriger mit Azure Blob Storage die folgenden Flags:

Shell
gh gei generate-script --github-source-org SOURCE \
  --github-target-org DESTINATION \
  --output FILENAME \
  --ghes-api-url GHES-API-URL

Wenn du GitHub Enterprise Server 3.7 oder niedriger mit AWS S3 nutzt, verwende die folgenden Flags:

Shell
gh gei generate-script --github-source-org SOURCE \
  --github-target-org DESTINATION \
  --output FILENAME \
  --ghes-api-url GHES-API-URL \
  --aws-bucket-name AWS-BUCKET-NAME

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.
GHES-API-URLDie URL für die API von deine GitHub Enterprise Server-Instanz, z. B. https://myghes.com/api/v3
AWS-BUCKET-NAMEDer Bucketname für deinen AWS S3-Bucket

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
--no-ssl-verifyWenn deine GitHub Enterprise Server-Instanz ein selbstsigniertes oder ungültiges SSL-Zertifikat verwendet, gibst du das Flag --no-ssl-verify an. Mit diesem Flag überspringt die GitHub CLI die Überprüfung des SSL-Zertifikats, wenn nur aus deiner Instanz Daten extrahiert werden. Alle anderen Aufrufe werden per SSL überprüft.
--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 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 6: Migrieren von Repositorys

Mit dem Befehl gh gei migrate-repo kannst mehrere Repositorys mit einem Migrationsskript oder einem einzelnen Repository migrieren.

Beim Migrieren von Repositorys führt die GEI extension of the GitHub CLI die folgenden Schritte aus:

  1. Herstellen einer Verbindung mit deine GitHub Enterprise Server-Instanz und Generieren von zwei Migrationsarchiven pro Repository (eines für die Git-Quelle und eines für die Metadaten)
  2. Hochladen der Migrationsarchive in den Blobspeicheranbieter deiner Wahl
  3. Starten der Migration in GitHub Enterprise Cloud mithilfe der URLs der Archive, die bei deinem Blobspeicheranbieter gespeichert sind
  4. Löschen des Migrationsarchivs von deinem lokalen Computer

Migrieren mehrerer Repositorys

Wenn du von GitHub Enterprise Server 3.7 oder einer früheren Version migrierst, musst du vor dem Ausführen des Skripts zusätzliche Umgebungsvariablen für die Authentifizierung bei deinem Blobspeicheranbieter festlegen.

  • Lege für Azure Blob Storage AZURE_STORAGE_CONNECTION_STRING auf die Verbindungszeichenfolge für dein Azure Storage-Konto fest.

    Es werden nur Verbindungszeichenfolgen mit Zugriffsschlüsseln für Speicherkonten unterstützt. Verbindungszeichenfolgen, die Shared Access Signatures (SAS) verwenden, werden nicht unterstützt. Weitere Informationen zu Zugriffsschlüsseln für Speicherkonten findest du unter Verwalten von Speicherkonto-Zugriffsschlüsseln in der Azure-Dokumentation.

  • Lege für AWS S3 die folgenden Umgebungsvariablen fest.

    • AWS_ACCESS_KEY_ID: Zugriffsschlüssel-ID Ihres Buckets
    • AWS_SECRET_ACCESS_KEY: geheimer Schlüssel deines Buckets
    • AWS_REGION: Die AWS-Region, in der sich dein Bucket befindet
    • AWS_SESSION_TOKEN: Das AWS-Sitzungstoken, wenn du temporäre AWS-Anmeldeinformationen verwendest (siehe Verwenden temporärer Anmeldeinformationen mit AWS-Ressourcen in der AWS-Dokumentation)

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

Du musst diesen Schritt von einem Computer aus ausführen, der auf die API für deine GitHub Enterprise Server-Instanz zugreifen kann. Wenn du über den Browser auf deine Instanz zugreifen kannst, hat der Computer den erforderlichen Zugriff.

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

Wenn du GitHub Enterprise Server 3.8 oder höher nutzt, verwende die folgenden Flags:

Shell
gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME --ghes-api-url GHES-API-URL

Wenn du von GitHub Enterprise Server 3.7 oder einer früheren Version migrierst und Azure Blob Storage als Blobspeicheranbieter nutzt, verwende die folgenden Flags für die Authentifizierung:

Shell
gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME \
    --ghes-api-url GHES-API-URL --azure-storage-connection-string "AZURE_STORAGE_CONNECTION_STRING"

Wenn du von GitHub Enterprise Server 3.7 oder einer früheren Version migrierst und Amazon S3 als Blobspeicheranbieter nutzt, verwende die folgenden Flags für die Authentifizierung:

Shell
gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME \
    --ghes-api-url GHES-API-URL --aws-bucket-name "AWS-BUCKET-NAME"

Platzhalter

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
GHES-API-URLDie URL für die API von deine GitHub Enterprise Server-Instanz, z. B. https://myghes.com/api/v3
AZURE_STORAGE_CONNECTION_STRINGDie Verbindungszeichenfolge für dein Azure Storage-Konto.

Stelle sicher, dass du die Verbindungszeichenfolge in Anführungszeichen setzt, da sie Zeichen enthält, die andernfalls wahrscheinlich von der Shell interpretiert werden.
AWS-BUCKET-NAMEDer Bucketname für deinen AWS S3-Bucket

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
--no-ssl-verifyWenn deine GitHub Enterprise Server-Instanz ein selbstsigniertes oder ungültiges SSL-Zertifikat verwendet, gibst du das Flag --no-ssl-verify an. Mit diesem Flag überspringt die GitHub CLI die Überprüfung des SSL-Zertifikats, wenn nur aus deiner Instanz Daten extrahiert werden. Alle anderen Aufrufe werden per SSL überprüft.
--skip-releasesWenn 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.
--target-repo-visibility TARGET-VISIBILITYRepositorys werden standardmäßig mit privater Sichtbarkeit migriert. Um die Sichtbarkeit festzulegen, können Sie das Flag --target-repo-visibility hinzufügen und private, public oder internal angeben. Wenn Sie zu Unternehmen mit verwalteten Benutzer*innen migrieren, sind öffentliche Repositorys nicht verfügbar.

Abbrechen der Migration

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 gei abort-migration --migration-id MIGRATION-ID

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

Nach Abschluss der Migration wird empfohlen, die Archive aus deinem Speichercontainer zu löschen. Wenn du weitere Migrationsvorgänge durchführen möchtest, löschst du das Archiv, das von der ADO2GH extension in deinem Speichercontainer platziert wurde. Wenn du mit der Migration fertig bist, kannst du den gesamten Container löschen.