Verwenden von GraphQL zum Migrieren von Repositorys von GitLab zu GitHub Enterprise Cloud

Schritt 0: Vorbereiten der Verwendung der GitHub GraphQL-API

Um GraphQL-Abfragen zu erstellen, musst du eigene Skripts schreiben oder einen HTTP-Client wie Insomnia verwenden.

Weitere Informationen zu den ersten Schritten mit der GitHub-GraphQL-API, einschließlich der Authentifizierung, findest du unter Erstellen von Aufrufen mit GraphQL.

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

Schritt 1: Holen Sie sich das ownerId für Ihr Migrationsziel

Verwende als Organisationsbesitzer*in in GitHub Enterprise Cloud die Abfrage GetOrgInfo, um die ownerId (auch als Organisations-ID bezeichnet) für die Organisation zurückzugeben, der du den Besitz der migrierten Repositorys zuordnen möchtest. Du benötigst die ownerId, um das Migrationsziel anzugeben.

Abfrage GetOrgInfo

query(
  $login: String!
){
  organization (login: $login)
  {
    login
    id
    name
    databaseId
  }
}

Abfragevariable	Beschreibung
login	Name deiner Organisation.

Antwort von GetOrgInfo

{
  "data": {
    "organization": {
      "login": "Octo",
      "id": "MDEyOk9yZ2FuaXphdGlvbjU2MTA=",
      "name": "Octo-org",
      "databaseId": 5610
    }
  }
}

In diesem Beispiel ist MDEyOk9yZ2FuaXphdGlvbjU2MTA= die Organisations-ID oder die ownerId, die du im nächsten Schritt verwendest.

Schritt 2: Ermitteln der Migrationsquelle

Du kannst eine Migrationsquelle mithilfe der Abfrage createMigrationSource einrichten. Du musst die ownerId oder die Organisations-ID angeben, die du mit der Abfrage GetOrgInfo abgerufen hast.

Ihre Migrationsquelle ist Ihre GitLab-Instanz.

createMigrationSource-Veränderung

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

Legen Sie url die vollständige URL Ihrer GitLab-Instanz fest, z https://gitlab.com . B. oder https://gitlab.example.com. Stelle sicher, dass du GITLAB für type verwendest.

Abfragevariable	Beschreibung
name	Ein Name für deine Migrationsquelle. Dieser Name dient deiner eigenen Referenz, sodass du eine beliebige Zeichenfolge angeben kannst.
ownerId	Die Organisations-ID deiner Organisation in GitHub Enterprise Cloud.

createMigrationSource Antwort

{
  "data": {
    "createMigrationSource": {
      "migrationSource": {
        "id": "MS_kgDaACQxYmYxOWU4Yi0wNzZmLTQ3NTMtOTdkZC1hNGUzZmYxN2U2YzA",
        "name": "GitLab Source",
        "url": "https://gitlab.com",
        "type": "GITLAB"
      }
    }
  }
}

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

Schritt 3: Generieren und Hosten Ihres Migrationsarchivs

Migrationen von GitLab sind archivbasiert. Anstatt während der Migration eine Verbindung mit Ihrer GitLab-Instanz herzustellen, importiert Sie ein Migrationsarchiv, GitHub Enterprise Importer das Sie aus Ihrem GitLab-Projekt generieren. Ein GitLab-Archiv ist eine einzelne Datei, die sowohl die Git-Quelle als auch die Metadaten des Repositorys enthält.

Bevor Sie die Migration starten, müssen Sie:

1. Generieren Sie ein Migrationsarchiv für das GitLab-Projekt, das Sie migrieren möchten.
2. Hosten Sie das Archiv unter einer URL, auf die GitHub Enterprise Cloud zugegriffen werden kann.

Sie geben diese URL als gitArchiveUrl Wert im nächsten Schritt an.

Migrationsarchiv generieren

Verwenden Sie die GitLab-Projektexport-API , um das Projekt zu exportieren, das Sie migrieren möchten. Das verwendete Token muss über den api Bereich und eine Rolle mit der Berechtigung zum Exportieren des Projekts verfügen. Weitere Informationen findest du unter Verwalten des Zugriffs für eine Migration von GitLab zu GitHub.

Legen Sie in den folgenden Anforderungen die GITLAB_PAT Umgebungsvariable auf das Token fest, das Sie in Verwalten des Zugriffs für eine Migration von GitLab zu GitHub erstellt haben. Ersetzen Sie den GITLAB-SERVER Host Ihrer GitLab-Instanz, z gitlab.com. B. durch GROUP%2FPROJECT den URL-codierten Pfad Ihres Projekts. Das Projekt acme-group/my-project wird z. B. als acme-group%2Fmy-projectcodiert. Schließen Sie für geschachtelte Untergruppen den vollständigen Pfad ein, z parent-group%2Fsubgroup%2Fmy-project. B. .

1. Planen Sie den Export.

   curl --request POST \
     --header "PRIVATE-TOKEN: $GITLAB_PAT" \
     "https://GITLAB-SERVER/api/v4/projects/GROUP%2FPROJECT/export"
   

2. Überprüfen Sie den Status des Exports. Wiederholen Sie diese Anforderung, bis export_status sie lautet finished.

   curl --header "PRIVATE-TOKEN: $GITLAB_PAT" \
     "https://GITLAB-SERVER/api/v4/projects/GROUP%2FPROJECT/export"
   

3. Laden Sie das Archiv herunter.

   curl --location \
     --header "PRIVATE-TOKEN: $GITLAB_PAT" \
     --output archive.tar.gz \
     "https://GITLAB-SERVER/api/v4/projects/GROUP%2FPROJECT/export/download"
   

Hosten des Archivs

Sie müssen das Archiv unter einer URL hosten, auf die GitHub Enterprise Cloud zugegriffen werden kann. Sie können das Archiv entweder in GitHub-owned blob storage einen externen BLOB-Speicheranbieter hochladen oder verwenden. Informationen zu externen Anbietern finden Sie unter Konfigurieren des Blobspeichers.

Um das Archiv GitHub-owned blob storagehochzuladen, benötigen Sie die Datenbank-ID Ihrer Organisation auf GitHub Enterprise Cloud. Ersetzen Sie ORGANIZATION den Namen Ihrer Organisation, um diese ID aus dem Feld in der id Antwort abzurufen.

curl --header "Authorization: Bearer YOUR-TOKEN" \
  "https://api.github.com/orgs/ORGANIZATION"

Laden Sie das Archiv mit einer POST Anforderung hoch, und ersetzen ORGANIZATION-ID Sie die Datenbank-ID Ihrer Organisation. Diese Anforderung funktioniert für Archive bis zu 100 MiB. Verwenden Sie für größere Archive einen externen BLOB-Speicheranbieter.

curl --request POST \
  --header "Authorization: Bearer YOUR-TOKEN" \
  --header "Content-Type: application/octet-stream" \
  --data-binary @archive.tar.gz \
  "https://uploads.github.com/organizations/ORGANIZATION-ID/gei/archive?name=archive.tar.gz"

Die Antwort enthält ein uri``gei://archive/GUIDFormat. Verwenden Sie diesen Wert im nächsten Schritt als .gitArchiveUrl

{
  "guid": "ff7b1a25-aa10-41a9-8e42-f170304b1c0d",
  "node_id": "MA_kgDaACRmZjdiMWEyNS1hYTEwLTQxYTktOGU0Mi1mMTcwMzA0YjFjMGQ",
  "name": "archive.tar.gz",
  "size": 7103,
  "uri": "gei://archive/ff7b1a25-aa10-41a9-8e42-f170304b1c0d",
  "created_at": "2024-11-13T12:35:45.761-08:00"
}

Schritt 4: 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-Veränderung

mutation startRepositoryMigration (
  $sourceId: ID!,
  $ownerId: ID!,
  $sourceRepositoryUrl: URI!,
  $repositoryName: String!,
  $continueOnError: Boolean!,
  $accessToken: String!,
  $githubPat: String!,
  $gitArchiveUrl: String!,
  $targetRepoVisibility: String!
){
  startRepositoryMigration( input: {
    sourceId: $sourceId,
    ownerId: $ownerId,
    repositoryName: $repositoryName,
    continueOnError: $continueOnError,
    accessToken: $accessToken,
    githubPat: $githubPat,
    targetRepoVisibility: $targetRepoVisibility,
    gitArchiveUrl: $gitArchiveUrl,
    sourceRepositoryUrl: $sourceRepositoryUrl,
  }) {
    repositoryMigration {
      id
      migrationSource {
        id
        name
        type
      }
      sourceUrl
    }
  }
}

Abfragevariable	Beschreibung
sourceId	Die id deiner Migrationsquelle, die von der createMigrationSource-Mutation zurückgegeben wurde.
ownerId	Die Organisations-ID deiner Organisation in GitHub Enterprise Cloud.
repositoryName	Ein 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.
continueOnError	Migrationseinstellung, 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.
githubPat	Das personal access token für deine Zielorganisation auf GitHub Enterprise Cloud.
accessToken	Das personal access token für deine Quelle.
targetRepoVisibility	Die Sichtbarkeit des neuen Repositorys. Muss private, public oder internal sein. Wenn sie nicht festgelegt wurde, wird dein Repository als privat migriert.

| gitArchiveUrl | Eine GitHub Enterprise CloudURL mit Zugriff auf das Migrationsarchiv, das Sie im vorherigen Schritt generiert haben. GitLab-Migrationen verwenden ein einzelnes Archiv, das sowohl die Git-Quelle als auch die Metadaten enthält, sodass Sie keine separate metadataArchiveUrlBereitstellen müssen.

| sourceRepositoryUrl | Die URL Ihres Quell-Repositorys auf GitLab mit dem Format https://GITLAB-SERVER/{group}/{project}. Schließen Sie für geschachtelte Untergruppen den vollständigen Pfad ein, z https://GITLAB-SERVER/{parent-group}/{subgroup}/{project}. B. . GitHub Enterprise Cloud stellt während der Migration keine Verbindung mit dieser URL her; es wird zur Referenz aufgezeichnet.

Da GitLab-Migrationen archivbasiert sind, GitHub Enterprise Cloud wird während der Migration keine Verbindung mit GitLab hergestellt. Die accessToken Variable ist von der Mutation erforderlich, wird aber nicht verwendet, sodass Sie sie auf einen beliebigen Platzhalterwert festlegen können, z not-used. B. .

Anforderungen personal access token finden Sie unter Verwalten des Zugriffs für eine Migration von GitLab zu GitHub.

Im nächsten Schritt verwendest du die von der startRepositoryMigration-Mutation zurückgegebene Migrations-ID, um den Migrationsstatus zu überprüfen.

Schritt 5: Überprüfen des Status Ihrer Migration

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

Abfragevariable	Beschreibung
id	Die id deiner Migration, die von der startRepositoryMigration-Mutation zurückgegeben wurde.

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

Weiterführende Lektüre

• Nachverfolgungsaufgaben