Projekte spiegeln

Sie möchten ein bestehendes Projekt von einer anderen Plattform wie GitHub übernehmen oder ein Projekt von der openCode-GitLab-Instanz auf eine andere Plattform (z. B. GitHub, Gitea) übertragen? Dies wird als Spiegelung (auf Englisch mirroring) bezeichnet. Hierfür gibt es drei Methoden:

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

Info

In der von openCode genutzten Version von GitLab ist eine Pull-Spiegelungen und eine Bidirektionale Spiegelung aktuell nicht direkt möglich. Eine Umsetzung über CI/CD-Pipelines ist möglich, erfordert jedoch fortgeschrittene Kenntnisse. Eine Anleitung zur Pull-Spiegelung über einer CI-Komponente finden Sie weiter unten.

So funktioniert die Push-Spiegelung

Beim Spiegeln wird ein Projekt von der openCode-GitLab-Instanz auf eine andere Plattform (z. B. GitHub, Gitea) übertragen.Voraussetzungen dafür sind Betreuer:innen-Rechte für das Projekt auf openCode. Das Zielprojekt (z. B. auf GitHub) sollte bereits existieren. Beim Push-Mirroring sendet die Quelle (openCode-GitLab-Instanz) aktiv Änderungen an das Ziel (HitHub, Gitea, etc.).

1. Ziel-URL kopieren

Öffnen Sie das Zielprojekt (z. B. auf GitHub oder GitLab) und klicken Sie auf die "Code-Schaltfläche" (in GitLab ist diese blau, in GitHub ist sie grün). In GitHub wählen Sie den SSH-Reiter und kopieren dort die angezeigte URL. In GitLab wählen Sie "Mit SSH klonen", um die URL zu kopieren.

2. Spiegelung einrichten

Gehen Sie in Ihrem openCode-Projekt zu Einstellungen > Repository. Scrollen Sie zu "Spiegelnde Repositorys" und klicken Sie auf "Hinzufügen". Fügen Sie die eben kopierte URL ein und passen Sie diese wiefolgt an:

• Fügen Sie vor die URL ein ssh:// hinzu und ersetzen Sie den Doppelpunkt (:) vor dem Namen des Projekts mit einem Schrägstrich (/).
• Wählen Sie als Authentifizierungsmethode "Öffentlicher SSH-Schlüssel"
• Setzen Sie den Nutzernamen auf "git"
• Klicken Sie auf "Repository spiegeln"

3. SSH-Schlüssel hinzufügen

Kopieren Sie den angezeigten öffentlichen SSH-Schlüssel und fügen Sie ihn im Zielprojekt als "Deploy Key" ein.

Im GitLab öffnen Sie dazu die Seite Ihres leeren GitLab-Projekts und navigieren zu Einstellungen > Repository. Öffnen Sie den Reiter Bereitstellungsschlüssel und klicken Sie auf die Schaltfläche "Neuen Schlüssel hinzufügen". Fügen Sie nun den Schlüssel aus der Zwischenablage hinein und wählen Sie nun einen aussagekräftigen Titel für Ihren Schlüssel.

Im GitHub öffnen Sie die Seite Ihres leeren GitHub-Projekts. Klicken Sie oben rechts auf die Schaltfläche "Settings" und navigieren Sie in der linken Seitenleiste zu Security > Deploy Keys. Bestätigen Sie "Add deploy key" und fügen Sie den Schlüssel aus der Zwischenablage ein und vergeben auch hier einen aussagekräftigen Namen.

Info

Das Spiegeln kann automatisch (zeitgesteuert) oder manuell erfolgen. Achten Sie darauf, dass keine privaten Daten ungewollt übernommen werden.

So funktioniert die Pull-Spiegelung

Das openCode-GitLab erlaubt aktuell keine automatische Pull-Spiegelung (Spiegelung eines Projekts von einem anderen Ort zur openCode-GitLab-Instanz) über die Oberfläche. Beim Pull-Mirroring initiiert das Ziel die Synchronisation. Es fragt die Quelle regelmäßig nach Änderungen ab.

Es gibt allerdings eine Alternative: Eine Umsetzung über CI/CD-Pipelines ist möglich, erfordert jedoch fortgeschrittene Kenntnisse. Das Ziel (die openCode-GitLab-Instanz) startet eine Pipeline. Diese Pipeline lädt die Daten von der Quelle (z. B. GitHub, Gitea usw.) auf eine temporäre Umgebung. Von dort werden Sie zurück ins Ziel-Repository gepusht.

1. Ausgangsprojekt anlegen

Legen Sie ein leeres Ausgangsprojekt auf der openCode-GitLab-Instanz an. Legen Sie in diesem einen neuen Branch an. 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:

.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

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.

Navigieren Sie auf der GitLab-Seite des Ausgangsprojekts zu Einstellungen > Access tokens. 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".

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

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

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

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