GitHub-Synchronisierung

Lassen Sie Benutzer ihre Projekte mit Repositorys auf GitHub oder GitHub Enterprise synchronisieren.

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

​

GitHub-Synchronisierung einrichten

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

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Besuchen Sie die Entwicklereinstellungen, um Ihre GitHub-OAuth-Anwendung zu erstellen, und kopieren Sie Ihre CLIENT_ID und Ihr SECRET.

Hinweis: Geben Sie beim Erstellen der OAuth App ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback unter Authorization callback URL ein. Ayakaleaf Pro bildet dieselbe Adresse aus OVERLEAF_SITE_URL, daher müssen Sie dafür in config/variables.env nichts festlegen.

Fügen Sie anschließend die folgenden Einstellungen zu Ihren Overleaf-Umgebungsvariablendateien hinzu.

config/variables.env

# used to encrypt the user's GitHub access token.
# How to generate: `openssl rand -hex 32`
GITHUB_TOKEN_CIPHER_PASSWORD=0123456789ABCDEFG # changed to yours

# Github Sync Settings
GITHUB_SYNC_ENABLED=true
GITHUB_SYNC_CLIENT_ID=
GITHUB_SYNC_CLIENT_SECRET=

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

Stellen Sie vor dem Konfigurieren der GitHub-OAuth-Callback-URL sicher, dass OVERLEAF_SITE_URL korrekt gesetzt ist.

Wenn Sie sich in einer Region mit eingeschränktem Netzwerkzugang befinden, müssen Sie möglicherweise einen Proxy konfigurieren, um auf GitHub zuzugreifen. Setzen Sie dazu die folgende Umgebungsvariable: GITHUB_SYNC_PROXY_URL=http://10.0.0.1:10808. Bitte stellen Sie sicher, dass Ihre Nutzung eines Proxys den örtlichen Gesetzen und Vorschriften entspricht.

GITHUB_SYNC_PROXY_URL muss ein standardmäßiger HTTP/HTTPS-Forward-Proxy sein (z. B. der HTTP-Port von Clash). GitHub-Download-Mirrors wie gh-proxy.org werden nicht unterstützt.

Verwenden Sie nicht 127.0.0.1 als Proxy-Host. Wenn der Proxy auf dem Host-Server läuft, verwenden Sie die LAN-IP-Adresse des Servers (z. B. 192.168.1.xx) und stellen Sie sicher, dass der Proxy Verbindungen von Geräten im lokalen Netzwerk akzeptiert.

​

GitHub Enterprise

Die Unterstützung für GitHub Enterprise ist ab v6.3.1 verfügbar. Frühere Versionen verbinden sich nur mit github.com, und die folgenden Variablen haben keine Wirkung.

Standardmäßig verbindet sich die GitHub-Synchronisierung mit github.com. Um GitHub Enterprise Server (selbst gehostet) oder GitHub Enterprise Cloud mit Datenresidenz (GHE.com) zu verwenden, setzen Sie GITHUB_SYNC_URL auf die Webadresse Ihrer Instanz, also die Adresse, mit der Sie Repositorys im Browser öffnen.

config/variables.env

# GitHub Enterprise Server
GITHUB_SYNC_URL=https://github.example.com

# or GitHub Enterprise Cloud with data residency
# GITHUB_SYNC_URL=https://octocorp.ghe.com

Die REST- und GraphQL-API-Endpunkte werden auf dieselbe Weise aus GITHUB_SYNC_URL abgeleitet wie bei der GitHub CLI:

GITHUB_SYNC_URL	REST-API	GraphQL-API
https://github.com (Standard)	https://api.github.com	https://api.github.com/graphql
https://SUBDOMAIN.ghe.com	https://api.SUBDOMAIN.ghe.com	https://api.SUBDOMAIN.ghe.com/graphql
https://HOST (alle anderen)	https://HOST/api/v3	https://HOST/api/graphql

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

Variable	Standardwert
GITHUB_SYNC_URL	https://github.com
GITHUB_SYNC_API_URL	Abgeleitet von GITHUB_SYNC_URL, siehe Tabelle oben
GITHUB_SYNC_GRAPHQL_URL	Abgeleitet von GITHUB_SYNC_API_URL, sofern gesetzt (/api/v3 wird zu /api/graphql, andernfalls wird /graphql angehängt), sonst von GITHUB_SYNC_URL

• Erstellen Sie die OAuth-Anwendung auf Ihrer Enterprise-Instanz (Settings → Developer settings → OAuth Apps). Eine Anwendung von github.com funktioniert dort nicht. Die Callback-URL ist dieselbe: ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback.
• GITHUB_SYNC_URL ist ausschließlich die Webadresse. Setzen Sie sie nicht auf eine API-Adresse wie https://api.github.com oder https://HOST/api/v3, und fügen Sie keinen Organisationspfad hinzu.
• Alle drei Adressen müssen auf dieselbe GitHub-Instanz verweisen.

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

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

​

Wer verknüpfen und synchronisieren kann

Wie in Overleaf Cloud kann nur der Projektbesitzer ein Projekt mit einem GitHub-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 GitHub-Repository exportieren	Der Projektbesitzer
Ein GitHub-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 GitHub über das GitHub-Konto des Benutzers, der synchronisiert. Daher verknüpft jeder Mitarbeitende, der synchronisiert, sein eigenes GitHub-Konto und muss berechtigt sein, auf den Standard-Branch des Repositorys zu pushen.
• Mitarbeitende mit reinem Leserecht können die GitHub-Synchronisierung für das Projekt nicht verwenden.

​

Q&A

Wie verknüpfe ich ein Projekt mit GitHub und synchronisiere es?

Antwort: Öffnen Sie im Editor Integrations und klicken Sie auf GitHub. Wenn Ihr GitHub-Konto noch nicht verknüpft ist, klicken Sie zuerst auf Link to your GitHub account. Geben Sie unter Export Project to GitHub einen Repository-Namen ein, wählen Sie unter Repository visibility die Option Private und klicken Sie auf Create a GitHub repository.

Danach öffnet dieselbe Karte Sync with GitHub, wo die neuen Commits in GitHub aufgelistet werden. Klicken Sie auf Sync, um Ihre Overleaf-Änderungen in den Standard-Branch zu committen und die GitHub-Änderungen in das Projekt zu übernehmen. Die Synchronisierung erfolgt in beide Richtungen, läuft aber nur, wenn jemand auf Sync klickt; eine zeitgesteuerte Synchronisierung gibt es nicht. Wenn sich beide Seiten geändert haben, führt Overleaf die Änderungen über einen temporären Branch namens overleaf-YYYY-MM-DD-HHMMSS zusammen. Hat dieser Merge einen Konflikt, führen Sie den Branch selbst in GitHub zusammen und klicken Sie dann auf I have manually merged. Continue.

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

Antwort: Wir empfehlen es nicht. Overleaf erkennt einen Force-Push, warnt davor und übernimmt den umgeschriebenen Branch, wobei die seit der letzten Synchronisierung in Overleaf vorgenommenen Änderungen zusammengeführt werden. Um Überraschungen zu vermeiden, schützen Sie den Standard-Branch in den Repository-Einstellungen vor Force-Pushes.

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

Antwort: Bitte tun Sie das nicht. Overleaf synchronisiert weiterhin mit dem Branch, mit dem das Projekt verknüpft wurde. 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.

Die GitHub-Synchronisierung zeigt „Something wrong with GitHub request“

Antwort: Diese Meldung bedeutet, dass der Server GitHub nicht erreichen konnte, zum Beispiel aufgrund eines Netzwerk-, DNS-, TLS- oder Proxy-Problems. Führen Sie bin/logs web aus, um den vollständigen Fehler zu sehen. Wenn der Server einen Proxy benötigt, um GitHub zu erreichen, setzen Sie GITHUB_SYNC_PROXY_URL.

Sollte ich „Expire user access tokens“ in der GitHub OAuth App deaktivieren?

Antwort: Ja. Die GitHub-Synchronisierung erneuert abgelaufene Token nicht. Bei aktivierten ablaufenden Token müssen Benutzer GitHub jedes Mal erneut verbinden, wenn ihr Token abläuft.

Muss meine Instanz aus dem Internet erreichbar sein?

Antwort: Nein. Das Verknüpfen eines Kontos erfolgt über den Browser des Benutzers, daher muss sich die OAuth-Callback-Adresse nur im Browser des Benutzers öffnen lassen. Der Server muss lediglich GitHub erreichen können; falls er dafür einen Proxy benötigt, setzen Sie GITHUB_SYNC_PROXY_URL. GitHub ruft Ihre Instanz nie auf: Ein Projekt wird nur synchronisiert, wenn ein Benutzer es im Editor synchronisiert.

Das Verknüpfen meines GitHub-Kontos schlägt fehl oder leitet mich ohne Verknüpfung zurück

Antwort: Prüfen Sie Folgendes in dieser Reihenfolge:

• Öffnen Sie Overleaf genau unter der Adresse, die in OVERLEAF_SITE_URL gesetzt ist. GitHub leitet Sie zu ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback zurück, und Ihre Anmeldung besteht nur unter der Adresse, von der aus Sie begonnen haben; ein anderer Host, eine andere IP-Adresse oder ein anderer Port endet daher auf der Anmeldeseite oder bei „Restricted, sorry you don’t have permission to load this page“.
• Die Authorization callback URL der OAuth App muss ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback lauten, mit demselben Schema, Host und Port.
• Eine Fehlerseite mit Failed to obtain access token from Git server bedeutet, dass GitHub kein Token zurückgegeben hat: Prüfen Sie GITHUB_SYNC_CLIENT_ID und GITHUB_SYNC_CLIENT_SECRET und ob der Server GitHub erreichen kann. Führen Sie bin/logs web aus, um den vollständigen Fehler zu sehen.

Führen Sie nach einer Änderung an config/variables.env den Befehl bin/up aus, um die Container neu zu erstellen.

Der Import eines Repositorys schlägt mit „EmptyZipFileError: empty_zip_file“ oder „unzip failed“ fehl

Antwort: Overleaf importiert das ZIP-Archiv des neuesten Commits auf dem Standard-Branch des Repositorys, und dieser Fehler bedeutet, dass das Archiv keine Datei enthält, die Overleaf importieren kann. Prüfen Sie den Standard-Branch auf GitHub:

• Er enthält die Projektdateien und nicht nur Dateien, die Overleaf beim Import überspringt: Dotfiles wie .gitignore und .gitmodules (.latexmkrc wird beibehalten) sowie Build-Dateien wie *.aux, *.log, *.bbl, *.synctex.gz, *.doc und *.docx.
• Die Dateien liegen nicht ausschließlich in Git-Submodulen. Das Archiv von GitHub enthält Submodule nur als leere Ordner.
• Die erwarteten Dateien befinden sich auf dem Standard-Branch und nicht auf einem anderen Branch. Der Import verwendet immer den Standard-Branch.

Der Import eines Repositorys schlägt mit „connect ECONNREFUSED“ zu „sharelatex:3054“ fehl

Antwort: V1_HISTORY_URL ist auf http://sharelatex:3054 gesetzt, einen Wert, den ältere Versionen dieser Dokumentation angegeben haben. Port 3054 gehört zum Dienst project-history, der nur innerhalb des Containers lauscht, während V1_HISTORY_URL auf history-v1 verweisen muss. Overleaf speichert jede Binärdatei (Bilder, PDFs) des importierten Repositorys in history-v1, daher schlägt der Import fehl; das Hochladen einer solchen Datei im Editor schlägt auf dieselbe Weise fehl. Setzen Sie in Ihrer docker-compose.yml beim Dienst sharelatex den Wert V1_HISTORY_URL: "http://sharelatex:3100/api" (siehe Git-Integration) und erstellen Sie den Container neu. Das Toolkit setzt diesen Wert bereits; prüfen Sie, dass docker-compose.override.yml ihn nicht überschreibt.