Gitea-Synchronisierung

Diese Funktion wurde von ayaka-notes/ayakaleaf-pro entwickelt. Sie wurde in v6.3.2 als Early Preview eingeführt und wird in v6.4.0 offiziell veröffentlicht, daher können sich Konfiguration und Verhalten noch ändern. Wir freuen uns über Ihr Feedback, falls Probleme auftreten.

Die Gitea-Synchronisierung funktioniert wie die GitHub-Synchronisierung und die GitLab-Synchronisierung: Benutzer verknüpfen ihr Gitea-Konto, exportieren Projekte in neue Gitea-Repositorys, importieren Gitea-Repositorys und synchronisieren Änderungen in beide Richtungen. Sie funktioniert mit Gitea ab Version 1.23, auf gitea.com oder auf Ihrer eigenen Instanz.

​

Gitea-Synchronisierung einrichten

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

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Erstellen Sie auf Ihrer Gitea-Instanz eine OAuth2-Anwendung unter Einstellungen → Anwendungen → OAuth2-Anwendungen verwalten (oder unter Website-Administration → Integrationen → Anwendungen für eine instanzweite Anwendung):

• Application name: z. B. Overleaf; Benutzer sehen diesen Namen, wenn sie die Anwendung autorisieren
• Redirect URIs: ${OVERLEAF_SITE_URL}/user/gitea-sync/oauth2/callback
• Confidential client: aktiviert

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

config/variables.env

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

# Gitea Sync Settings
GITEA_SYNC_ENABLED=true
GITEA_SYNC_CLIENT_ID=
GITEA_SYNC_CLIENT_SECRET=

# Web address of your Gitea (its ROOT_URL), defaults to https://gitea.com
# GITEA_SYNC_URL=https://gitea.example.com

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

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

Overleaf fordert beim Verknüpfen des Kontos alle Berechtigungen an, die eine Synchronisierung benötigt, sodass Benutzer das Konto nie wegen einer fehlenden Berechtigung erneut verknüpfen müssen:

Scope	Verwendet für
write:repository	Repositorys, ihre Dateien (einschließlich CI-Workflows unter .gitea/workflows), Branches und Pull Requests
write:user	Erstellen eines Repositorys des Benutzers beim Export (Gitea verlangt diesen Scope für POST /user/repos)
write:organization	Auflisten der Organisationen des Benutzers und Erstellen eines Repositorys einer Organisation beim Export

Gitea zeigt diese Scopes an, wenn der Benutzer die Anwendung autorisiert, und beschränkt das Token darauf.

Gitea-Zugriffstoken laufen nach einer Stunde ab ([oauth2] ACCESS_TOKEN_EXPIRATION_TIME). Overleaf erneuert sie mit dem Refresh-Token, das Gitea zusammen mit ihnen ausstellt – auch dann, wenn Gitea Refresh-Token bei der Verwendung verbraucht (INVALIDATE_REFRESH_TOKENS = true) –, sodass Benutzer verknüpft bleiben, bis sie die Verknüpfung aufheben oder die Anwendung in Gitea widerrufen.

​

Ihre Gitea-Instanz

Setzen Sie GITEA_SYNC_URL auf die Webadresse Ihrer Instanz, also ihre ROOT_URL – die Adresse, mit der Sie Repositorys im Browser öffnen. Die REST-API wird daraus abgeleitet:

Variable	Standardwert
GITEA_SYNC_URL	https://gitea.com
GITEA_SYNC_API_URL	${GITEA_SYNC_URL}/api/v1

Ein unter einem Unterpfad bereitgestelltes Gitea funktioniert ebenfalls, z. B. GITEA_SYNC_URL=https://example.com/gitea. Setzen Sie GITEA_SYNC_API_URL nur, wenn Ihre Instanz die API an einer anderen Stelle bereitstellt, zum Beispiel hinter einem API-Gateway.

• Erstellen Sie die OAuth2-Anwendung auf der Instanz, die Sie in GITEA_SYNC_URL festlegen. Eine Anwendung von einer anderen Instanz funktioniert nicht.
• GITEA_SYNC_URL ist ausschließlich die Webadresse. Fügen Sie weder /api/v1 noch einen Benutzer- oder Organisationspfad hinzu.
• Overleaf committet über die Datei-API von Gitea, die den Web-Editor benötigt: Lassen Sie [repository.editor] aktiviert (Standardeinstellung).

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/gitea-ca.pem.

Verknüpfte Konten und Projekte gehören zu der Instanz, mit der sie verknüpft wurden. Bevor Sie GITEA_SYNC_URL auf eine andere Instanz umstellen, bitten Sie die Benutzer, die Verknüpfung ihres Gitea-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 Gitea zuzugreifen. Setzen Sie dazu die folgende Umgebungsvariable: GITEA_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 Gitea-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 Gitea-Repository exportieren	Der Projektbesitzer
Ein Gitea-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 Gitea über das Gitea-Konto des Benutzers, der synchronisiert. Daher verknüpft jeder Mitarbeitende, der synchronisiert, sein eigenes Gitea-Konto und muss berechtigt sein, auf den Standard-Branch des Repositorys zu pushen.
• Mitarbeitende mit reinem Leserecht können die Gitea-Synchronisierung für das Projekt nicht verwenden.
• Wenn Sie die Verknüpfung des Kontos in Overleaf aufheben, wird dessen Token verworfen. Gitea bietet keine API, um es zu widerrufen. Widerrufen Sie die Berechtigung daher bei Bedarf zusätzlich in Gitea unter Einstellungen → Anwendungen.

​

So funktioniert die Synchronisierung mit Gitea

• Berechtigungen: Benutzer müssen berechtigt sein, auf den Standard-Branch des verknüpften Repositorys zu pushen. Wenn eine Branch-Schutzregel dem Benutzer das Pushen darauf nicht erlaubt, 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 Gitea geändert wurde, committet Overleaf seine Änderungen in einen temporären Branch namens overleaf-YYYY-MM-DD-HHMMSS und führt ihn über einen Pull Request mit dem Standard-Merge-Stil des Repositorys zusammen, da Gitea keine API zum Zusammenführen von Branches ohne Pull Request bietet. Nach dem Merge löscht Overleaf den temporären Branch. Der zusammengeführte Pull Request bleibt als Nachweis im Repository erhalten.
• Merge-Regeln: Overleaf umgeht niemals den Branch-Schutz des Repositorys. Wenn der Pull Request einen Konflikt aufweist oder Genehmigungen bzw. erfolgreiche Statusprüfungen benötigt, bleibt er offen, und Overleaf bittet den Benutzer, ihn in Gitea zusammenzuführen und anschließend die Synchronisierung fortzusetzen.
• CI-Workflows: Overleaf zeigt Dotfiles wie .gitea/workflows/ nicht an und lässt sie im Repository unverändert. Commits von Overleaf starten Gitea Actions wie jeder andere Commit.

​

Q&A

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

Antwort: Bitte lassen Sie Force-Pushes auf den Standard-Branch deaktiviert, z. B. mit einer Branch-Schutzregel. Overleaf kann einen umgeschriebenen Branch übernehmen, aber die Gitea-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.

Unterstützt die Gitea-Synchronisierung Git LFS?

Antwort: Nein. Overleaf-Projekte unterstützen Git Large File Storage nicht. Dateien, die von Git LFS verwaltet werden, erscheinen in Overleaf als LFS-Pointer-Dateien und nicht mit ihrem Inhalt. Committen Sie Bilder und PDFs stattdessen direkt in das Repository.

Funktioniert sie mit SHA-256-Repositorys?

Antwort: Noch nicht. Overleaf vergleicht Dateien anhand ihrer SHA-1-IDs, daher schreibt in einem Repository, das mit dem SHA-256-Objektformat erstellt wurde, jeder Pull alle Dateien neu, auch unveränderte. Es geht nichts verloren, aber bitte verwenden Sie das Standardformat SHA-1.

Funktioniert sie mit Forgejo?

Antwort: Die Gitea-Synchronisierung wurde ausschließlich für Gitea entwickelt und getestet.