Von GitHub zu GitLab migrieren, ohne Umwege

Wer einen Wechsel zu GitLab erwägt, stellt fast immer zuerst dieselbe Frage: Wie aufwendig ist die Migration? Für die meisten DevSecOps-Teams ist die Sorge vor der großen Umzugsarbeit die größte Hürde auf dem Weg zu einer einheitlichen, KI-nativen DevSecOps-Plattform.

Der Umzug nach GitLab ist einfacher als je zuvor. Der eingebaute Importer holt den weitaus größten Teil der Projektdaten automatisch und im Hintergrund herüber. Und die Übersetzung der CI/CD-Pipeline, bislang der eine Teil, der Handarbeit verlangte, übernimmt inzwischen weitgehend GitLab Duo. Unsere KI-native Assistenz wandelt GitHub-Actions-Workflows in GitLab CI/CD um.

Dieser Beitrag geht die Migration von Anfang bis Ende durch:

• Welche Daten von GitHub nach GitLab migrieren und was davon automatisch, mit Einschränkungen oder manuell läuft
• Welche Voraussetzungen in GitLab 18.x tatsächlich nötig sind, weniger als vermutet
• Drei Wege für den Import: Oberfläche mit OAuth, Personal Access Token und die REST-API für größere Umzüge
• Wie sich GitHub Actions in GitLab CI/CD überführen lassen, auf dem klassischen Weg und zügig mit GitLab Duo
• Aus welchen anderen Plattformen GitLab importieren kann

Los geht's.

Welche Daten migrieren von GitHub nach GitLab?

Der eingebaute GitHub-Importer von GitLab wird direkt aus der Projektanlage heraus aufgerufen und läuft als Hintergrundjob. Ein Import lässt sich also anstoßen und dann sich selbst überlassen. Die meisten Projektdaten kommen automatisch mit. Ein kleinerer Teil ist optional zuschaltbar oder hat Einschränkungen, die man vorher kennen sollte.

Die folgende Tabelle zeigt, was migriert und auf welche Weise:

Wie werden die Rollen abgebildet?

GitHub und GitLab benennen Rollen unterschiedlich, deshalb findet während der Migration eine Zuordnung statt. Werden Mitarbeitende importiert, gilt folgende Abbildung:

Voraussetzungen

Die Voraussetzungen sind über die Jahre einfacher geworden. Insbesondere braucht nicht mehr jede GitHub-Autorenschaft eine passende öffentliche E-Mail-Adresse in GitLab. Die Zuordnung von Beiträgen übernimmt GitLab inzwischen automatisch über das Contribution Mapping (ab GitLab 17.8). Mehr dazu weiter unten.

Für den Import von GitHub.com oder GitHub Enterprise Server nach GitLab.com oder auf eine GitLab-Self-Managed-Instanz ist nötig:

• Zugriff auf das GitHub-Quellprojekt, das importiert werden soll.
• Die Rolle Maintainer oder Owner in der GitLab-Zielgruppe.
• GitHub als Importquelle aktiviert. Auf GitLab.com ist das standardmäßig der Fall. Bei GitLab Self-Managed schaltet die Administration es unter Importquellen frei.
• Die GitHub-Organisation darf den Zugriff durch Drittanwendungen nicht einschränken (oder der Zugriff wird bei der Autorisierung eigens gewährt).

Dazu kommen zwei situationsabhängige Voraussetzungen:

• Sollen Git-LFS-Objekte mit? Dann LFS im Zielprojekt aktivieren, bevor der Import startet.
• Sollen Mitarbeitende mit? Dann braucht das Token den Scope read:org und mindestens Write- oder Maintain-Zugriff auf das GitHub-Projekt.

Passende E-Mail-Adressen sind nicht mehr nötig

Früher wanderte die Beitragshistorie nur dann sauber mit, wenn die öffentliche E-Mail-Adresse jeder GitHub-Person mit ihrer GitLab-Adresse übereinstimmte. Heute legt GitLab Platzhalter-Konten für jede GitHub-Autorenschaft, -Zuweisung oder -Review ohne passendes GitLab-Konto an und bewahrt deren Beiträge.

Nach dem Import weist eine Person mit Owner- oder Maintainer-Rolle unter Mitglieder → Platzhalter jeden Platzhalter dem realen GitLab-Konto zu, das die Zuordnung dann annimmt. Migrieren lässt sich also zuerst, die Zuordnung folgt danach.

Den Import durchführen

Für den Import gibt es drei Wege. Welcher passt, hängt von Quelle und Umfang ab.

Weg 1: Oberfläche mit GitHub-OAuth (empfohlen für GitLab.com)

Für die meisten Teams der kürzeste Weg.

1. In einer Gruppe Create project → Import project → GitHub wählen (oder direkt unter gitlab.com/projects/new#import_project starten).
2. Die Schaltfläche Authenticate with GitHub betätigen und die OAuth-Anwendung bestätigen.
3. Bei Repositorys einer Organisation neben dem Organisationsnamen auf Grant klicken, um den Zugriff zu autorisieren.
4. Die Repositorys über die Reiter Owner / Collaborated / Organization filtern und die gewünschten auswählen. Dabei lassen sie sich umbenennen und einem GitLab-Namensraum zuordnen.
5. Die optionalen Schalter setzen (siehe Tabelle unten) und auf Import klicken. Der Import läuft als Hintergrundjob, man kann die Seite verlassen und später nachsehen.

Optionale Schalter:

Weg 2: Personal Access Token (wenn OAuth nicht eingerichtet ist)

Ist OAuth nicht eingerichtet, erfolgt die Authentifizierung über ein Token.

1. Unter github.com/settings/tokens/new ein klassisches Personal Access Token mit dem Scope repo anlegen (dazu read:org, wenn Mitarbeitende oder LFS importiert werden). Hinweis: Fine-grained Tokens werden nicht unterstützt.
2. In GitLab in einer Gruppe Create project → Import project → GitHub wählen.
3. Das Token einfügen, Authenticate wählen und dieselben Schritte zur Auswahl und Konfiguration durchlaufen wie beim OAuth-Weg.

Weg 3: REST-API (Massenimporte und Skripte)

Für viele Repositorys auf einmal, für skriptgesteuerte Umzüge oder für öffentliche Repositorys, die einem nicht gehören, eignet sich die Import-API.

      curl --request POST \
  --url "https://gitlab.com/api/v4/import/github" \
  --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "personal_access_token": "<github_classic_pat>",
    "repo_id": 12345678,
    "target_namespace": "my-group",
    "new_name": "imported-project",
    "optional_stages": {
      "single_endpoint_notes_import": true,
      "attachments_import": true,
      "collaborators_import": true
    }
  }'

    

Den Fortschritt verfolgen:

      curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "https://gitlab.com/api/v4/projects/<project_id>/import"

    

Dafür braucht es ein klassisches GitHub-PAT mit dem Scope repo und ein GitLab-PAT mit dem Scope api.

Den Import prüfen

Ist der Import durch, empfiehlt sich eine kurze Kontrolle:

1. Das neue Projekt öffnen und das Statusbanner von scheduled über started zu finished verfolgen. Meldet es partially completed, nachsehen, welche Objekte fehlgeschlagen sind.
2. Die Zahl der Branches, Tags, Commit-SHAs, Issues, Merge Requests, Labels und Meilensteine mit der Quelle vergleichen.
3. Prüfen, ob importierte Objekte das Kennzeichen Imported tragen.

Ein erneuter Import legt eine frische Kopie an, in ein bestehendes Projekt lässt sich nicht importieren. Sieht etwas nicht richtig aus, hilft also löschen und neu laufen lassen.

GitHub und GitLab während einer schrittweisen Migration parallel betreiben

Eine Migration muss kein harter Schnitt sein. Die meisten Teams ziehen nach und nach um: GitHub bleibt in Betrieb, während GitLab aufgebaut wird, die Pipelines geprüft werden und ein Team nach dem anderen wechselt. GitLab ist darauf ausgelegt, in dieser Übergangszeit neben GitHub zu bestehen, sodass sich GitLab schrittweise einführen lässt, statt über Nacht umzuschalten.

So arbeiten beide Plattformen während der Migration nebeneinander:

• Repositorys per Pull-Mirroring synchron halten. GitLab kann ein GitHub-Repository per Pull-Mirroring spiegeln und neue Branches und Commits in festen Abständen übernehmen. Entwicklungsteams pushen weiter nach GitHub, während GitLab aktuell bleibt. Damit steht eine stets aktuelle, nur lesbare Kopie bereit, an der sich CI/CD und Abläufe erproben lassen, bevor jemand die gewohnte Arbeitsweise ändert. Steht der Wechsel an, lässt sich auf Push-Mirroring umstellen, sodass Änderungen aus GitLab zurück nach GitHub fließen, solange dort noch Teams arbeiten.
• Pipelines auf GitHub-Repositorys laufen lassen. Wer GitLab CI/CD erproben möchte, bevor der Code umzieht, verbindet über CI/CD für externe Repositorys ein GitHub-Repository mit GitLab. Pipelines laufen dann bei jedem Push und jedem Pull Request und melden den Status nach GitHub zurück. So lässt sich die umgestellte .gitlab-ci.yml an echten Commits prüfen, während die maßgebliche Quelle noch in GitHub liegt.
• CI/CD-Status nach GitHub zurückmelden. Über die GitHub-Integration schickt GitLab Pipeline- und Commit-Status an GitHub. Wer noch nicht gewechselt hat, sieht grüne Haken und Build-Ergebnisse weiterhin in der gewohnten Oberfläche.
• Team für Team, Repository für Repository umziehen. Weil der Importer projektweise arbeitet, kann zuerst ein Team seine Repositorys mitnehmen und sich einrichten. Die nächste Gruppe folgt, sobald die Unebenheiten beseitigt sind. Noch nicht migrierte Gruppen und Untergruppen zeigen so lange weiter auf GitHub.

GitHub Actions nach GitLab CI/CD überführen

CI/CD ist der Teil der Migration, der nicht automatisch läuft. Er ist zugleich die Gelegenheit, die Pipelines zu modernisieren. Viele Kernkonzepte lassen sich sauber übertragen:

Ein wichtiger Unterschied: In GitLab laufen Stages nacheinander und Jobs innerhalb einer Stage parallel. Mit needs: lässt sich daraus ein ausdrücklicher gerichteter azyklischer Graph (DAG) bauen.

Zügig: GitLab Duo die Workflows umwandeln lassen

Die GitLab Duo Agent Platform enthält einen Flow "Convert to GitLab CI/CD", der GitHub-Actions-Workflows in eine .gitlab-ci.yml übersetzt. Statt von Grund auf neu zu schreiben, prüft man dann einen Entwurf.

GitLab Duo hilft über die gesamte Migration hinweg, nicht nur beim Umwandeln:

• Planung: je Repository einen Migrationsplan und eine Einschätzung der Komplexität aus den Workflow-Dateien erzeugen.
• Umwandlung: Der Convert-Flow schreibt Actions-Workflows nach GitLab CI/CD um und erhält dabei Matrix-Builds, Job-Abhängigkeiten, Artefakte und bedingte Regeln.
• Dokumentation: READMEs, Badges und Verweise aktualisieren (etwa "Pull Request" zu "Merge Request").
• Prüfung: importierte Zahlen gegenprüfen und Fehlendes sichtbar machen.
• Fehlersuche: Der Flow "Fix CI/CD pipeline" analysiert einen fehlgeschlagenen Job, benennt die wahrscheinliche Ursache und bereitet Änderungsvorschläge vor.
• Aufräumen: GitLab-eigene Optimierungen vorschlagen, etwa Caching, needs:-DAGs und CI/CD-Komponenten.

GitLab Duo Agentic Chat zieht Kontext aus Issues, Merge Requests und Pipelines heran und beantwortet Fragen direkt in der Plattform. Duo Code Suggestions unterstützen beim Bearbeiten der .gitlab-ci.yml in der Web-IDE.

Steht GitLab Duo in der eigenen Umgebung nicht zur Verfügung, gelingen dieselben Umwandlungen auch mit einem Frontier-Modell und einem strukturierten Prompt. Ein Prompt, der verlässliche Ergebnisse liefert:

Convert this GitHub Actions workflow to GitLab CI/CD. Preserve matrix builds, job dependencies, artifacts, and conditional rules. Return a valid .gitlab-ci.yml.

Ein paar Leitplanken für den Einsatz jeder KI-Assistenz bei der Migration: niemals Secrets, Tokens oder interne Hostnamen einfügen, erzeugtes YAML immer mit dem CI-Lint-Werkzeug von GitLab prüfen und die Ausgabe als Entwurf zur Durchsicht behandeln, nicht als fertigen Commit.

Von Hand: ein Beispiel im Vergleich

Ob GitLab Duo den Code entwirft oder er von Hand entsteht, es hilft, die Übertragung einmal zu sehen. Hier ein typischer GitHub-Actions-Workflow zum Bauen und Testen:

      name: CI
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '18' }
      - run: npm install
      - run: npm test
      - run: npm run build

    

Und das Gegenstück in GitLab CI/CD. Der Checkout entfällt (GitLab klont selbst), aus runs-on wird image, und jeder Schritt wird zu einer Zeile in script::

      stages: [test, build]

# GitLab-maintained SAST is one line away
# a nice upgrade to add during migration.
include:
  - template: Jobs/SAST.gitlab-ci.yml

test:
  stage: test
  image: node:18
  script:
    - npm install
    - npm test

build:
  stage: build
  image: node:18
  script:
    - npm install
    - npm run build
  artifacts:
    paths: [dist/]

    

Matrix-Builds übertragen sich ebenso direkt, aus strategy.matrix wird parallel.matrix:

      test:
  image: node:${NODE_VERSION}
  parallel:
    matrix:
      - NODE_VERSION: ['16', '18', '20']
  script:
    - npm install
    - npm test

    

Und bedingte Deployments bilden sich über rules: ab:

      deploy:
  stage: deploy
  script: ./deploy.sh
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

    

Sobald die .gitlab-ci.yml committet ist, startet GitLab die Pipeline sofort. Mehr dazu steht in der Dokumentation zu GitLab CI/CD.

Aus welchen anderen Plattformen kann GitLab importieren?

GitHub ist nicht die einzige Quelle. Der Importer von GitLab unterstützt die Migration aus mehreren weiteren Plattformen mit einem Klick:

• Bitbucket Cloud
• Bitbucket Server (Stash)
• FogBugz
• Gitea
• Repository per URL
• Manifest-Datei (AOSP)
• Jira (nur Issues)

Zu diesen Migrationen gibt es außerdem Dokumentation:

• SVN
• ClearCase
• CVS
• Perforce
• TFVC

Danke fürs Lesen. Eine Migration muss nicht der beängstigende Teil beim Wechsel auf eine neue Plattform sein. GitLab holt die Daten automatisch herüber, GitLab Duo übernimmt die CI/CD-Umwandlung, und der Fokus bleibt auf dem Ausliefern. Mehr dazu über die folgenden Verweise:

• Kostenlose Testversion der GitLab Duo Agent Platform
• Dokumentation zur Projektmigration von GitHub nach GitLab
• Verfügbare Projekt-Importer
• GitLab Duo Agent Platform
• Dokumentation zu GitLab CI/CD