GitLab-synchronisatie

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

GitLab-synchronisatie werkt zoals GitHub-synchronisatie: gebruikers koppelen hun GitLab-account, exporteren projecten naar nieuwe GitLab-projecten, importeren GitLab-repository’s en synchroniseren wijzigingen in beide richtingen. Het werkt met GitLab.com en met zelfbeheerde GitLab 15.10 of later (Community en Enterprise Edition).

​

GitLab-synchronisatie instellen

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

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Maak een OAuth-applicatie aan op je GitLab-instantie, onder User settings → Applications (of Admin area → Applications voor een applicatie voor de hele instantie):

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

Kopieer de Application ID en het Secret en voeg vervolgens de volgende instellingen toe aan je Overleaf-omgevingsvariabelenbestanden.

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

Zorg ervoor dat OVERLEAF_SITE_URL correct is ingesteld voordat je de GitLab OAuth-redirect-URI configureert.

GitLab-toegangstokens verlopen na twee uur. Overleaf vernieuwt ze met de refresh-token die GitLab erbij uitgeeft, zodat gebruikers gekoppeld blijven totdat ze de koppeling verbreken of de applicatie in GitLab intrekken.

​

Zelfbeheerde GitLab

Stel GITLAB_SYNC_URL in op het webadres van je instantie, het adres waarmee je projecten in de browser opent. De REST API wordt daarvan afgeleid:

Variabele	Standaardwaarde
GITLAB_SYNC_URL	https://gitlab.com
GITLAB_SYNC_API_URL	${GITLAB_SYNC_URL}/api/v4

Stel GITLAB_SYNC_API_URL alleen in wanneer je instantie de API ergens anders aanbiedt, bijvoorbeeld achter een API-gateway.

• Maak de OAuth-applicatie aan op de instantie die je in GITLAB_SYNC_URL instelt; een applicatie van gitlab.com werkt niet op een zelfbeheerde instantie.
• GITLAB_SYNC_URL is alleen het webadres. Voeg geen /api/v4 of groepspad toe.

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

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

Als je je in een regio met beperkte netwerktoegang bevindt, moet je mogelijk een proxy configureren om GitLab te bereiken. Stel de volgende omgevingsvariabele in: GITLAB_SYNC_PROXY_URL=http://10.0.0.1:10808. Dit moet een standaard HTTP/HTTPS-forwardproxy zijn en mag geen 127.0.0.1 gebruiken.

​

Wie kan koppelen en synchroniseren

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

Actie	Wie kan het doen
Een project exporteren naar een nieuwe GitLab-repository	De projecteigenaar
Een GitLab-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 GitLab via het GitLab-account van de gebruiker die synchroniseert. Elke medewerker die synchroniseert, koppelt dus zijn eigen GitLab-account en moet naar de standaardbranch van de repository mogen pushen.
• Medewerkers met alleen leesrechten kunnen GitLab-synchronisatie niet voor het project gebruiken.

​

Hoe synchroniseren met GitLab werkt

• Rechten: gebruikers moeten naar de standaardbranch van het gekoppelde project mogen pushen. Wanneer de standaardbranch beschermd is en de gebruiker er niet naar mag pushen, vraagt Overleaf hem contact op te nemen met de projecteigenaar, net als bij een repository waartoe hij geen toegang meer heeft.
• Mergen: wanneer een project zowel in Overleaf als in GitLab is gewijzigd, commit Overleaf zijn wijzigingen naar een tijdelijke branch met de naam overleaf-YYYY-MM-DD-HHMMSS en merget deze via een merge request, omdat GitLab geen API heeft om branches zonder merge request te mergen. Na de merge verwijdert Overleaf de tijdelijke branch en het merge request. Alleen beheerders en projecteigenaren mogen merge requests in GitLab verwijderen, dus voor andere gebruikers blijft het gemergede merge request in het project staan.
• Mergeregels: Overleaf omzeilt nooit de mergeregels van het project. Wanneer het merge request een conflict heeft, of een goedkeuring of een geslaagde pipeline vereist, blijft het open en vraagt Overleaf de gebruiker het in GitLab te mergen en daarna verder te synchroniseren.
• Pipelines: commits vanuit Overleaf starten pipelines zoals elke andere commit. Als je project pipelines voor merge requests uitvoert en vereist dat ze slagen, wachten merges vanuit Overleaf daarop, zoals hierboven beschreven.

​

Q&A

Kan ik force pushen naar de standaardbranch?

Antwoord: Houd force pushes naar de standaardbranch uitgeschakeld. Dit is de standaardinstelling van GitLab: de standaardbranch van een nieuw project is beschermd en niemand kan ernaar force pushen. Overleaf kan een herschreven branch overnemen, maar GitLab-synchronisatie is ontworpen voor een standaardbranch waarvan de geschiedenis alleen groeit.

Kan ik de standaardbranch van een gekoppeld project hernoemen?

Antwoord: Nee. Overleaf blijft synchroniseren met de branch waaraan het project is gekoppeld, dus synchronisaties mislukken zodra die branch is hernoemd of verwijderd. 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.