GitHub-synchronisatie

Laat gebruikers hun projecten synchroniseren met repository’s op GitHub of GitHub Enterprise.

Deze functie is ontwikkeld door ayaka-notes/ayakaleaf-pro en aangepast door yu-i-i/overleaf-cep. Ze is geïntroduceerd in v6.2.0 en latere versies. Ze bevindt zich nog in de bètafase. We horen graag je feedback als je problemen hebt.

​

GitHub-synchronisatie instellen

Je moet eerst git-bridge inschakelen voordat je GitHub-synchronisatie kunt gebruiken.

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Ga naar de ontwikkelaarsinstellingen om je GitHub OAuth-applicatie aan te maken en kopieer je CLIENT_ID en SECRET.

Opmerking: voer bij het aanmaken van de OAuth App ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback in bij Authorization callback URL. Ayakaleaf Pro stelt hetzelfde adres samen uit OVERLEAF_SITE_URL, dus daarvoor hoef je niets in te stellen in config/variables.env.

Voeg vervolgens de volgende instellingen toe aan je Overleaf-omgevingsvariabelenbestanden.

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

Zorg ervoor dat OVERLEAF_SITE_URL correct is ingesteld voordat je de GitHub OAuth-callback-URL configureert.

Als je je in een regio met beperkte netwerktoegang bevindt, moet je mogelijk een proxy configureren om GitHub te bereiken. Stel de volgende omgevingsvariabele in: GITHUB_SYNC_PROXY_URL=http://10.0.0.1:10808. Zorg ervoor dat je gebruik van een proxy voldoet aan de lokale wet- en regelgeving.

GITHUB_SYNC_PROXY_URL moet een standaard HTTP/HTTPS-forwardproxy zijn (bijvoorbeeld de HTTP-poort van Clash). GitHub-downloadmirrors zoals gh-proxy.org worden niet ondersteund.

Gebruik 127.0.0.1 niet als proxyhost. Als de proxy op de hostserver draait, gebruik dan het LAN-IP-adres van de server (zoals 192.168.1.xx) en zorg ervoor dat de proxy is geconfigureerd om verbindingen van apparaten in het lokale netwerk te accepteren.

​

GitHub Enterprise

Ondersteuning voor GitHub Enterprise is geïntroduceerd in v6.3.1 en latere versies. Eerdere versies maken alleen verbinding met github.com en de onderstaande variabelen hebben dan geen effect.

Standaard maakt GitHub-synchronisatie verbinding met github.com. Om GitHub Enterprise Server (zelf gehost) of GitHub Enterprise Cloud met dataresidentie (GHE.com) te gebruiken, stel je GITHUB_SYNC_URL in op het webadres van je instantie, het adres waarmee je repository’s in de browser opent.

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

De REST- en GraphQL-API-endpoints worden op dezelfde manier van GITHUB_SYNC_URL afgeleid als de GitHub CLI dat doet:

GITHUB_SYNC_URL	REST API	GraphQL API
https://github.com (standaard)	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 (elke andere)	https://HOST/api/v3	https://HOST/api/graphql

Stel de API-endpoints alleen in wanneer je instantie ze ergens anders aanbiedt, bijvoorbeeld achter een API-gateway:

Variabele	Standaardwaarde
GITHUB_SYNC_URL	https://github.com
GITHUB_SYNC_API_URL	Afgeleid van GITHUB_SYNC_URL, zie de tabel hierboven
GITHUB_SYNC_GRAPHQL_URL	Afgeleid van GITHUB_SYNC_API_URL wanneer die is ingesteld (/api/v3 wordt /api/graphql, anders wordt /graphql toegevoegd), en anders van GITHUB_SYNC_URL

• Maak de OAuth-applicatie aan op je enterprise-instantie (Settings → Developer settings → OAuth Apps); een applicatie van github.com werkt daar niet. De callback-URL is hetzelfde: ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback.
• GITHUB_SYNC_URL is alleen het webadres. Stel het niet in op een API-adres zoals https://api.github.com of https://HOST/api/v3, en voeg geen organisatiepad toe.
• Alle drie de adressen moeten naar dezelfde GitHub-instantie verwijzen.

Als je instantie een certificaat van een private CA gebruikt, koppel het CA-certificaat dan in de container en laat NODE_EXTRA_CA_CERTS ernaar verwijzen, bijvoorbeeld NODE_EXTRA_CA_CERTS=/var/lib/overleaf/certs/github-ca.pem.

Gekoppelde accounts en projecten horen bij de instantie waarmee ze zijn gekoppeld. Vraag gebruikers om de koppeling van hun GitHub-account en projecten te verbreken voordat je GITHUB_SYNC_URL naar een andere instantie overzet.

​

Wie kan koppelen en synchroniseren

Net als bij Overleaf Cloud kan alleen de projecteigenaar een project aan een GitHub-repository koppelen. Zodra het gekoppeld is, kan elke medewerker met bewerkrechten het synchroniseren.

Actie	Wie kan het doen
Een project exporteren naar een nieuwe GitHub-repository	De projecteigenaar
Een GitHub-repository importeren in een nieuw project	Elke gebruiker, die eigenaar wordt van het nieuwe project
Een gekoppeld project pullen, pushen en mergen	De eigenaar en medewerkers met bewerkrechten
De koppeling van een project met zijn repository verbreken	De projecteigenaar

• Overleaf communiceert met GitHub via het GitHub-account van de gebruiker die synchroniseert. Elke medewerker die synchroniseert, koppelt dus zijn eigen GitHub-account en moet naar de standaardbranch van de repository mogen pushen.
• Medewerkers met alleen leesrechten kunnen GitHub-synchronisatie niet voor het project gebruiken.

​

Q&A

Hoe koppel ik een project aan GitHub en synchroniseer ik het?

Antwoord: Open in de editor Integrations en klik op GitHub. Als je GitHub-account nog niet is gekoppeld, klik dan eerst op Link to your GitHub account. Voer in Export Project to GitHub een repositorynaam in, kies Private onder Repository visibility en klik op Create a GitHub repository.

Daarna opent dezelfde kaart Sync with GitHub, met een lijst van de nieuwe commits in GitHub. Klik op Sync om je Overleaf-wijzigingen naar de standaardbranch te committen en de GitHub-wijzigingen in het project op te nemen. Synchronisatie werkt in beide richtingen, maar wordt alleen uitgevoerd wanneer iemand op Sync klikt; er is geen geplande synchronisatie. Wanneer beide kanten zijn gewijzigd, voegt Overleaf samen via een tijdelijke branch met de naam overleaf-YYYY-MM-DD-HHMMSS. Als die merge een conflict oplevert, voeg de branch dan zelf samen in GitHub en klik vervolgens op I have manually merged. Continue.

Kan ik force pushen naar de standaardbranch?

Antwoord: Dat raden we af. Overleaf detecteert een force push, waarschuwt ervoor en neemt de herschreven branch over, waarbij de wijzigingen die sinds de laatste synchronisatie in Overleaf zijn gemaakt worden samengevoegd. Om verrassingen te voorkomen, kun je de standaardbranch in de repository-instellingen beschermen tegen force pushes.

Kan ik de standaardbranch van een gekoppeld project hernoemen?

Antwoord: Doe dat liever niet. Overleaf blijft synchroniseren met de branch waaraan het project is gekoppeld. Om met een andere branch te synchroniseren, verbreek je de koppeling van het project en importeer je de repository vervolgens in een nieuw project, dat de huidige standaardbranch gebruikt.

GitHub-synchronisatie toont 'Something wrong with GitHub request'

Antwoord: Dit bericht betekent dat de server GitHub niet kon bereiken, bijvoorbeeld door een netwerk-, DNS-, TLS- of proxyprobleem. Voer bin/logs web uit om de volledige fout te zien. Als de server een proxy nodig heeft om GitHub te bereiken, stel dan GITHUB_SYNC_PROXY_URL in.

Moet ik 'Expire user access tokens' uitschakelen in de GitHub OAuth App?

Antwoord: Ja. GitHub-synchronisatie vernieuwt verlopen tokens niet. Als verlopende tokens zijn ingeschakeld, moeten gebruikers GitHub opnieuw koppelen telkens wanneer hun token verloopt.

Moet mijn instantie bereikbaar zijn vanaf internet?

Antwoord: Nee. Het koppelen van een account verloopt via de browser van de gebruiker, dus het OAuth-callbackadres hoeft alleen te openen in de browser van de gebruiker. De server hoeft alleen GitHub te kunnen bereiken; als daarvoor een proxy nodig is, stel dan GITHUB_SYNC_PROXY_URL in. GitHub roept je instantie nooit aan: een project wordt alleen gesynchroniseerd wanneer een gebruiker het in de editor synchroniseert.

Het koppelen van mijn GitHub-account mislukt of stuurt me terug zonder te koppelen

Antwoord: Controleer het volgende, in deze volgorde:

• Open Overleaf op exact het adres dat in OVERLEAF_SITE_URL is ingesteld. GitHub stuurt je terug naar ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback, en je login bestaat alleen op het adres waarvan je bent begonnen, dus een andere host, ander IP-adres of andere poort eindigt op de inlogpagina of op „Restricted, sorry you don’t have permission to load this page”.
• De Authorization callback URL van de OAuth App moet ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback zijn, met hetzelfde schema, dezelfde host en dezelfde poort.
• Een foutpagina met Failed to obtain access token from Git server betekent dat GitHub geen token heeft teruggegeven: controleer GITHUB_SYNC_CLIENT_ID en GITHUB_SYNC_CLIENT_SECRET, en of de server GitHub kan bereiken. Voer bin/logs web uit om de volledige fout te zien.

Voer na het wijzigen van config/variables.env bin/up uit om de containers opnieuw aan te maken.

Het importeren van een repository mislukt met „EmptyZipFileError: empty_zip_file” of „unzip failed”

Antwoord: Overleaf importeert het zip-archief van de nieuwste commit op de standaardbranch van de repository, en deze fout betekent dat dat archief geen bestand bevat dat Overleaf kan importeren. Controleer de standaardbranch op GitHub:

• Deze bevat de projectbestanden, niet alleen bestanden die Overleaf bij het importeren overslaat: dotfiles zoals .gitignore en .gitmodules (.latexmkrc blijft behouden), en buildbestanden zoals *.aux, *.log, *.bbl, *.synctex.gz, *.doc en *.docx.
• De bestanden staan niet alleen in Git-submodules. Het archief van GitHub laat submodules achter als lege mappen.
• De bestanden die je verwacht, staan op de standaardbranch en niet op een andere branch. Importeren gebruikt altijd de standaardbranch.

Het importeren van een repository mislukt met „connect ECONNREFUSED” naar „sharelatex:3054”

Antwoord: V1_HISTORY_URL is ingesteld op http://sharelatex:3054, een waarde die oudere versies van deze documentatie gaven. Poort 3054 is de service project-history, die alleen binnen de container luistert, terwijl V1_HISTORY_URL naar history-v1 moet verwijzen. Overleaf slaat elk binair bestand (afbeeldingen, pdf’s) van de geïmporteerde repository op in history-v1, dus het importeren mislukt; het uploaden van zo’n bestand in de editor mislukt op dezelfde manier. Stel in je docker-compose.yml V1_HISTORY_URL: "http://sharelatex:3100/api" in op de service sharelatex (zie Git-integratie) en maak de container opnieuw aan. De Toolkit stelt deze waarde al in; controleer of docker-compose.override.yml deze niet overschrijft.