GitLab-Synchronisierung

Diese Funktion wurde von ayaka-notes/ayakaleaf-pro entwickelt. Sie ist ab v6.4.0 verfügbar und befindet sich noch im Beta-Status. Wir freuen uns über Ihr Feedback, falls Probleme auftreten.

Die GitLab-Synchronisierung funktioniert wie die GitHub-Synchronisierung: Benutzer verknüpfen ihr GitLab-Konto, exportieren Projekte in neue GitLab-Projekte, importieren GitLab-Repositorys und synchronisieren Änderungen in beide Richtungen. Sie funktioniert mit GitLab.com und mit selbstverwaltetem GitLab ab Version 15.10 (Community und Enterprise Edition).

​

GitLab-Synchronisierung einrichten

Sie müssen zuerst git-bridge aktivieren, bevor Sie die GitLab-Synchronisierung verwenden können.

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Erstellen Sie auf Ihrer GitLab-Instanz eine OAuth-Anwendung unter Benutzereinstellungen → Anwendungen (oder unter Admin-Bereich → Anwendungen für eine instanzweite Anwendung):

• Redirect URI: ${OVERLEAF_SITE_URL}/user/gitlab-sync/oauth2/callback
• Confidential: aktiviert
• Scopes: api

Kopieren Sie die Application ID und das Secret und fügen Sie anschließend die folgenden Einstellungen zu Ihren Overleaf-Umgebungsvariablendateien hinzu.

config/variables.env

# used to encrypt the user's GitLab access and refresh tokens.
# How to generate: `openssl rand -hex 32`
GITLAB_TOKEN_CIPHER_PASSWORD=0123456789ABCDEFG # changed to yours

# GitLab Sync Settings
GITLAB_SYNC_ENABLED=true
GITLAB_SYNC_CLIENT_ID=
GITLAB_SYNC_CLIENT_SECRET=

# Web address of your GitLab, defaults to https://gitlab.com
# GITLAB_SYNC_URL=https://gitlab.example.com

# OAuth callback is: ${OVERLEAF_SITE_URL}/user/gitlab-sync/oauth2/callback
# (Optional) GITLAB_SYNC_PROXY_URL=http://10.0.0.1:10808

Stellen Sie vor dem Konfigurieren der GitLab-OAuth-Redirect-URI sicher, dass OVERLEAF_SITE_URL korrekt gesetzt ist.

GitLab-Zugriffstoken laufen nach zwei Stunden ab. Overleaf erneuert sie mit dem Refresh-Token, das GitLab zusammen mit ihnen ausstellt, sodass Benutzer verknüpft bleiben, bis sie die Verknüpfung aufheben oder die Anwendung in GitLab widerrufen.

​

Selbstverwaltetes GitLab

Setzen Sie GITLAB_SYNC_URL auf die Webadresse Ihrer Instanz, also die Adresse, mit der Sie Projekte im Browser öffnen. Die REST-API wird daraus abgeleitet:

Variable	Standardwert
GITLAB_SYNC_URL	https://gitlab.com
GITLAB_SYNC_API_URL	${GITLAB_SYNC_URL}/api/v4

Setzen Sie GITLAB_SYNC_API_URL nur, wenn Ihre Instanz die API an einer anderen Stelle bereitstellt, zum Beispiel hinter einem API-Gateway.

• Erstellen Sie die OAuth-Anwendung auf der Instanz, die Sie in GITLAB_SYNC_URL festlegen. Eine Anwendung von gitlab.com funktioniert nicht auf einer selbstverwalteten Instanz.
• GITLAB_SYNC_URL ist ausschließlich die Webadresse. Fügen Sie weder /api/v4 noch einen Gruppenpfad hinzu.

Wenn Ihre Instanz ein Zertifikat einer privaten CA verwendet, binden Sie das CA-Zertifikat in den Container ein und lassen Sie NODE_EXTRA_CA_CERTS darauf verweisen, z. B. NODE_EXTRA_CA_CERTS=/var/lib/overleaf/certs/gitlab-ca.pem.

Verknüpfte Konten und Projekte gehören zu der Instanz, mit der sie verknüpft wurden. Bevor Sie GITLAB_SYNC_URL auf eine andere Instanz umstellen, bitten Sie die Benutzer, die Verknüpfung ihres GitLab-Kontos und ihrer Projekte aufzuheben.

Wenn Sie sich in einer Region mit eingeschränktem Netzwerkzugang befinden, müssen Sie möglicherweise einen Proxy konfigurieren, um auf GitLab zuzugreifen. Setzen Sie dazu die folgende Umgebungsvariable: GITLAB_SYNC_PROXY_URL=http://10.0.0.1:10808. Es muss sich um einen standardmäßigen HTTP/HTTPS-Forward-Proxy handeln, und 127.0.0.1 darf nicht verwendet werden.

​

Wer verknüpfen und synchronisieren kann

Wie in Overleaf Cloud kann nur der Projektbesitzer ein Projekt mit einem GitLab-Repository verknüpfen. Sobald es verknüpft ist, kann jeder Mitarbeitende mit Bearbeitungsrechten es synchronisieren.

Aktion	Wer sie ausführen kann
Ein Projekt in ein neues GitLab-Repository exportieren	Der Projektbesitzer
Ein GitLab-Repository in ein neues Projekt importieren	Jeder Benutzer, der dadurch Besitzer des neuen Projekts wird
Pull, Push und Merge eines verknüpften Projekts	Der Besitzer und Mitarbeitende mit Bearbeitungsrechten
Die Verknüpfung eines Projekts mit seinem Repository aufheben	Der Projektbesitzer

• Overleaf kommuniziert mit GitLab über das GitLab-Konto des Benutzers, der synchronisiert. Daher verknüpft jeder Mitarbeitende, der synchronisiert, sein eigenes GitLab-Konto und muss berechtigt sein, auf den Standard-Branch des Repositorys zu pushen.
• Mitarbeitende mit reinem Leserecht können die GitLab-Synchronisierung für das Projekt nicht verwenden.

​

So funktioniert die Synchronisierung mit GitLab

• Berechtigungen: Benutzer müssen berechtigt sein, auf den Standard-Branch des verknüpften Projekts zu pushen. Ist der Standard-Branch geschützt und darf der Benutzer nicht darauf pushen, bittet Overleaf ihn, sich an den Projektbesitzer zu wenden – wie bei einem Repository, auf das er keinen Zugriff mehr hat.
• Zusammenführen: Wenn ein Projekt sowohl in Overleaf als auch in GitLab geändert wurde, committet Overleaf seine Änderungen in einen temporären Branch namens overleaf-YYYY-MM-DD-HHMMSS und führt ihn über einen Merge Request zusammen, da GitLab keine API zum Zusammenführen von Branches ohne Merge Request bietet. Nach dem Merge löscht Overleaf den temporären Branch und den Merge Request. In GitLab dürfen nur Administratoren und Projektbesitzer Merge Requests löschen, daher bleibt der zusammengeführte Merge Request bei anderen Benutzern im Projekt erhalten.
• Merge-Regeln: Overleaf umgeht niemals die Merge-Regeln des Projekts. Wenn der Merge Request einen Konflikt aufweist oder eine Genehmigung bzw. eine erfolgreiche Pipeline benötigt, bleibt er offen, und Overleaf bittet den Benutzer, ihn in GitLab zusammenzuführen und anschließend die Synchronisierung fortzusetzen.
• Pipelines: Commits von Overleaf starten Pipelines wie jeder andere Commit. Wenn Ihr Projekt Pipelines für Merge Requests ausführt und deren Erfolg voraussetzt, warten Merges von Overleaf darauf, wie oben beschrieben.

​

Q&A

Kann ich einen Force-Push auf den Standard-Branch ausführen?

Antwort: Bitte lassen Sie Force-Pushes auf den Standard-Branch deaktiviert. Dies ist die Standardeinstellung von GitLab: Der Standard-Branch eines neuen Projekts ist geschützt, und niemand kann einen Force-Push darauf ausführen. Overleaf kann einen umgeschriebenen Branch übernehmen, aber die GitLab-Synchronisierung ist für einen Standard-Branch ausgelegt, dessen Historie nur wächst.

Kann ich den Standard-Branch eines verknüpften Projekts umbenennen?

Antwort: Nein. Overleaf synchronisiert weiterhin mit dem Branch, mit dem das Projekt verknüpft wurde, sodass Synchronisierungen fehlschlagen, sobald dieser Branch umbenannt oder entfernt wird. Um mit einem anderen Branch zu synchronisieren, heben Sie die Verknüpfung des Projekts auf und importieren Sie das Repository anschließend in ein neues Projekt, das den aktuellen Standard-Branch verwendet.