Skip to content

Das Spiegeln eines Projekts

Auswahl der richtigen Methode

Es gibt drei Methoden, um ein Projekt zu spiegeln (auf Englisch mirroring):

  • Push: Spiegelung eines Projekts von der openCode-GitLab-Instanz zu einem anderen Ort
  • Pull: Spiegelung eines Projekts von einem anderen Ort zur openCode-GitLab-Instanz
  • Bidirektional: Spiegeln in zwei Richtungen

Hinweis

In der von openCode genutzten Version von GitLab ist ein Pull-Spiegelung und ein bidirektionales-Spiegeln nicht verfügbar.

Es gibt aber die Möglichkeit über eine CI-Komponente eine Pull-Spiegelung umzusetzen. Eine Anleitung zur Pull-Spiegelung über einer CI-Komponente finden Sie hier.

Diese Anleitung erfordert allerdings Vorwissen über CI-Scripts und Pipelines in GitLab.

Push-Spiegelung

Bei einer Push-Spiegelung wird das Ausgangsprojekt an einer anderen Stelle hochgeladen. Das Ausgangsprojekt liegt dabei auf dem openCode GitLab. Das Zielprojekt kann dagegen auch auf anderen Plattformen, z.B. GitHub, Gitea, Forgejo gehostet werden.

1. Kopieren der Ziel-URL für das Ausgangsprojekt

  1. Öffnen Sie die Seite eines leeren Projekts (= Zielprojekt), zu welchem Ihr Ausgangsprojekt gespiegelt werden soll.

  2. Kopieren Sie die URL für den SSH-Zugriff auf das angelegte Zielprojekt:

    • URL eines GitHub-Projekts:

      • Öffnen Sie das GitHub-Projekt, welches Sie spiegeln wollen.
      • Drücken Sie nun auf die grüne Code-Schaltfläche und wählen Sie den Reiter SSH aus.
      • Kopieren Sie nun die entsprechende URL in die Zwischenablage:

      URL zum SSH-Zugriff eines Projekts auf GitLab kopieren

    • URL eines GitLab-Projekts:

      • Öffnen Sie das GitLab-Projekt, welches Sie spiegeln wollen.
      • Drücken Sie nun auf die blaue Code-Schaltfläche.
      • Kopieren Sie die URL unter "Mit SSH klonen" in die Zwischenablage

      URL zum SSH-Zugriff eines Projekts auf GitLab kopieren

2. Hinzufügen einer Spiegelung zum Ausgangsprojekt

Hinweis

Sie müssen in dem Ausgangsprojekt die Rechte einer/eines Betreuer(in) haben.

  1. Öffnen Sie das Projekt, welches Sie an anderer Stelle spiegeln wollen.
  2. Navigieren Sie nun in der linken Leiste zu: Einstellungen > Repository.
  3. Öffnen Sie anschließend den Reiter Spiegelnde Repositorys.
  4. Klicken Sie nun auf die Schaltfläche Hinzufügen.

Sie sollten nun folgende Einstellungen sehen:

Oberfläche mit den Einstellungen zum Spiegeln eines Projekts

Fahren Sie zum Ausfüllen dieser Einstellungen mit den nächsten Schritten fort:

  1. Fügen Sie die kopierte URL in das Feld Git-Repository-URL ein.
  2. Nehmen Sie nun folgende Änderungen an der URL vor:
    • Fügen Sie vor die URL ein ssh:// hinzu.
    • Ersetzen Sie den Doppelpunkt (:) vor dem Namen des Projekts mit einem Schrägstrich (/).
  3. Legen Sie nun als Authentifizierungsmethode die Methode Öffentlicher SSH-Schlüssel fest.
  4. Setzen Sie Ihren Nutzer:innen-Namen im Feld Nutzername auf git.
  5. Bestätigen Sie Ihre Eingaben indem Sie auf die Schaltfläche Repository spiegeln klicken.

3. Zugriff auf das Zielprojekt mittels eines öffentlichen SSH-Schlüssels erlauben

3.1 Kopieren des öffentlichen SSH-Schlüssel des zu spiegelnden Projekts

  1. Laden Sie die Seite des GitLab-Projekts, welches Sie spiegeln wollen.
  2. Öffnen Sie Einstellungen > Repository.
  3. Öffnen Sie den Reiter Spiegelnde Repositorys.
  4. Sie sollten nun den zuvor angelegten Eintrag sehen. Drücken Sie in diesem Eintrag nun auf die Schaltfläche (🔃), um den öffentlichen Schlüssel zu kopieren:

Kopieren des öffentlichen Schlüssels eines GitLab-Projekts

3.2 Hinzufügen des Schlüssels zu dem Projekt, auf das Sie Ihr Projekt spiegeln wollen

Dieser Schritt unterscheidet sich je nach Plattform, auf die Sie Ihr Projekt spiegeln wollen.

  • Einstellungen eines GitLab-Projekts:
    1. Öffnen Sie die Seite Ihres leeren GitLab-Projekts.
    2. Navigieren Sie zu Einstellungen > Repository.
    3. Öffnen Sie den Reiter Bereitstellungsschlüssel.
    4. Drücken Sie nun auf die Schaltfläche Neuen Schlüssel hinzufügen.
    5. Fügen Sie nun den Schlüssel aus der Zwischenablage hinein.
    6. Wählen Sie nun einen aussagekräftigen Titel für Ihren Schlüssel.

  • Einstellungen eines GitHub-Projekts:

    1. Öffnen Sie die Seite Ihres leeren GitHub-Projekts.
    2. Drücken Sie auf die Schaltfläche Settings (oben rechts).

    3. Navigieren Sie in der linken Seitenleiste zu Security > Deploy Keys.

      Auswählen der Option Security > Deploy Keys

    4. Drücken Sie nun auf die Schaltfläche Add deploy key.

      Öffentlichen Schlüssel einem GitHub-Projekt hinzufügen

    5. Fügen Sie nun den öffentlichen Schlüssel aus der Zwischenablage hinzu. Geben Sie diesem darüber hinaus einen aussagekräftigen Namen.

Info

Die Anleitung für eine Push-Spiegelung orientiert sich maßgeblich an der (englischsprachigen) Dokumentation von GitLab zum Repository mirroring.

Pull-Spiegelung

Bei einer Pull-Spiegelung wird ein Ausgangsprojekt von einem Zielprojekt (auf der openCode-GitLab-Instanz) heruntergeladen.

Verständnis: Wie funktioniert Pull-Mirroring?

Bevor wir loslegen, ist es hilfreich, die beteiligten Komponenten und deren Rollen zu verstehen:

  • Quelle: Das Repository, aus dem Inhalte stammen. Es enthält bereits Daten.
  • Ziel: Das Repository, das Inhalte übernehmen soll.

Richtung der Synchronisation

  • Beim Pull-Mirroring initiiert das Ziel die Synchronisation: Es fragt die Quelle regelmäßig nach Änderungen ab.
  • Beim Push-Mirroring sendet die Quelle aktiv Änderungen an das Ziel.

Besonderheit beim Pull-Mirroring mit CI

Da GitLab-CE ein Pull-Mirroring nicht direkt unterstützt, wird ein Umweg genutzt: - Das Ziel (unsere GitLab-Instanz) startet eine Pipeline. - Diese Pipeline lädt die Daten von der Quelle (z. B. GitHub) auf eine temporäre Umgebung. - Von dort werden Sie zurück ins Ziel-Repository gepusht.

Es handelt sich also um einen indirekten Ablauf: Quelle → CI → Ziel, wobei CI und Ziel im selben GitLab liegen.

1. Anlegen des Ausgangsprojekts

  1. Legen Sie ein leeres Ausgangsprojekt auf der openCode-GitLab-Instanz an.
  2. Legen Sie in diesem Ausgangsprojekt einen neuen Branch an. In diesem Beispiel wird dieser Branch mit pull-mirroring bezeichnet. Sie können aber auch eine beliebige andere Bezeichnung wählen.

  3. Legen Sie nun auf dem neu erstellen Branch folgendes GitLab CI-Script (.gitlab-ci.yml) an:

    • Passen Sie dabei den Link des Zielprojekts (target_url) an.

    Info

    Dieses Skript bindet folgende CI/CD-Komponente ein.

    .gitlab-ci.yml
    include:
- component: $CI_SERVER_FQDN/pull-mirroring/component/pull-mirroring@1.0.1
inputs:
    target_url: https://gitlab.opencode.de/ZIELPROJEKT            # Link zum Zielprojekt, welches zum Ausgangsprojekt heruntergeladen werden soll; kann auch ein GitHub-Repo seinauch auf https://github.com/... sein
    # http_protocol:                                              # (https) (access token only) Allows you to switch to `http`
    access_token_name: $GITLAB_PAT_NAME                           # (ci-mirroring) The name of the access token with the `write_repository` permission
    access_token: $GITLAB_PAT                                     # (null) The access token value
    # ssh_user:                                                   # (git) The SSH username
    # ssh_key:                                                    # (null) The path to the base64 encoded SSH private key
    # ssh_key_public:                                             # (null) The path to the base64 encoded SSH public key
    # stage:                                                      # (mirroring) The name of the stage for the job to be associated with
    # remote_name:                                                # (upstream) The name of the remote added to fetch `target_url` updates
    git_push_opt: --force                                         # ('') Options to pass to the `git push` command

stages:
- build
- mirroring
    1. Link zu dem Zielprojekt, welches zum Ausgangsprojekt heruntergeladen werden soll.

2. Zugriff auf das Ausgangsprojekt ermöglichen

Info

Anstatt den Zugriff über ein Zugriffstoken zu ermöglichen, können Sie auch einen Zugriff über einen SSH-Schlüssel einrichten. Hierzu müssen Sie auch die entsprechenden Optionen in der .gitlab-ci.yml-Datei anpassen.

  1. Navigieren Sie auf der GitLab-Seite des Ausgangsprojekts zu Einstellungen > Access tokens.
  2. Erstellen Sie über die Schaltfläche Neuen Token hinzufügen einen neuen Zugriffstoken:
    • Vergeben Sie einen aussagekräftigen Token-Namen und merken Sie sich diese exakte Bezeichnung (oder speichern Sie diese in einem Passwort-Manager).
    • Wählen Sie die Rolle Developer aus.
    • Wählen Sie folgende Geltungsbereiche aus: write_repository, read repository.
    • Bestätigen Sie die Erstellung eines neuen Projekt-Zugriffstokens über die (blaue) Schaltfläche "Projekt-Zugriffstoken erstellen".
  3. Kopieren Sie anschießend auf der Seite, die sich nun geöffnet hat, den neu erstellen Zugriffstoken über die Schaltfläche Projekt-Zugriffstoken kopieren in die Zwischenablage (oder speichern diese in einem Passwort-Manager): Gitlab Projekt-Zugriffstoken kopieren
  4. Fügen Sie den erstellen Zugriffstoken zu den CI/CD-Variablen hinzu:
    • Navigieren Sie in der Navigationsleiste (auf der linken Seite) nun zu Einstellungen > CI/CD.
    • Öffnen Sie den Reiter Variablen.
    • Klicken Sie auf die Schaltfläche Variable hinzufügen.
    • Geben Sie nun im Feld Schlüssel den Wert GITLAB_PAT an.
    • Fügen Sie in das Feld Wert den Zugriffstoken aus der Zwischenablage (oder dem Passwort-Manager) aus Schritt 3 hinzu (achten Sie darauf, dass am Ende des Codes keine neue leere Zeile hinzugefügt wird).
    • Klicken Sie nun auf die Schaltfläche Variable hinzufügen
  5. Fügen Sie die Variable mit dem Schlüssel GITLAB_PAT_NAME und der Bezeichnung des Zugrifftokens aus Schritt 2 zu den CI/CD-Variablen hinzu.

Hinweis

Falls das Spiegeln trotz korrekt gesetzter Variablen nicht funktioniert:

  • Branch-Schutz prüfen: Der genutzte Branch (z. B. pull-mirroring) darf nicht geschützt sein. Andernfalls ist kein Push aus der Pipeline möglich – auch dann nicht, wenn Push erzwingen aktiviert ist. Entfernen Sie ggf. den Branchschutz unter Repository > Geschützte Branches.
  • Variablen-Schutz prüfen: Die CI/CD-Variablen GITLAB_PAT und GITLAB_PAT_NAME dürfen nicht als geschützt markiert sein, wenn Sie in einem ungeschützten Branch verwendet werden.

3. Eine regelmäßige Synchronisierung einrichten

  1. Öffnen Sie auf der GitLab-Projektseite Build > Pipeline-Zeitpläne
  2. Klicken Sie auf die (blaue) Schaltfläche Erstelle einen neuen Pipeline-Zeitplan.
  3. Geben Sie eine aussagekräftige Beschreibung für den Pipeline-Zeitplan an.
  4. Wählen Sie ein Intervallmuster aus.
  5. Erstellen Sie den neuen Pipeline-Zeitplan über die entsprechende (blaue) Schaltfläche.