Synchronisation GitLab

Cette fonctionnalité est développée par ayaka-notes/ayakaleaf-pro. Elle est disponible à partir de la v6.4.0. Elle est encore en version bêta : vos retours nous sont précieux si vous rencontrez un problème.

La synchronisation GitLab fonctionne comme la synchronisation GitHub : les utilisateurs lient leur compte GitLab, exportent des projets vers de nouveaux projets GitLab, importent des dépôts GitLab et synchronisent les modifications dans les deux sens. Elle fonctionne avec GitLab.com et avec les instances GitLab autogérées en version 15.10 ou ultérieure (Community et Enterprise Edition).

​

Configurer la synchronisation GitLab

Vous devez d’abord activer git-bridge avant d’utiliser la synchronisation GitLab.

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Créez une application OAuth sur votre instance GitLab, dans User settings → Applications (ou Admin area → Applications pour une application à l’échelle de l’instance) :

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

Copiez l’Application ID et le Secret, puis ajoutez les paramètres suivants à vos fichiers de variables d’environnement Overleaf.

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

Avant de configurer l’URI de redirection OAuth de GitLab, assurez-vous que OVERLEAF_SITE_URL est correctement défini.

Les jetons d’accès GitLab expirent au bout de deux heures. Overleaf les renouvelle grâce au jeton d’actualisation que GitLab émet avec eux, de sorte que les utilisateurs restent liés jusqu’à ce qu’ils délient leur compte ou révoquent l’application dans GitLab.

​

GitLab autogéré

Définissez GITLAB_SYNC_URL sur l’adresse web de votre instance, celle que vous utilisez pour ouvrir les projets dans le navigateur. L’API REST en est déduite :

Variable	Valeur par défaut
GITLAB_SYNC_URL	https://gitlab.com
GITLAB_SYNC_API_URL	${GITLAB_SYNC_URL}/api/v4

Ne définissez GITLAB_SYNC_API_URL que si votre instance expose l’API ailleurs, par exemple derrière une passerelle d’API.

• Créez l’application OAuth sur l’instance définie dans GITLAB_SYNC_URL : une application créée sur gitlab.com ne fonctionne pas sur une instance autogérée.
• GITLAB_SYNC_URL correspond uniquement à l’adresse web. N’y ajoutez pas /api/v4 ni de chemin de groupe.

Si votre instance utilise un certificat émis par une autorité de certification privée, montez le certificat de l’autorité dans le conteneur et faites pointer NODE_EXTRA_CA_CERTS vers celui-ci, par exemple NODE_EXTRA_CA_CERTS=/var/lib/overleaf/certs/gitlab-ca.pem.

Les comptes et projets liés appartiennent à l’instance avec laquelle ils ont été liés. Avant de faire pointer GITLAB_SYNC_URL vers une autre instance, demandez aux utilisateurs de délier leur compte GitLab et leurs projets.

Si vous vous trouvez dans une région où l’accès au réseau est restreint, vous devrez peut-être configurer un proxy pour accéder à GitLab. Définissez la variable d’environnement suivante : GITLAB_SYNC_PROXY_URL=http://10.0.0.1:10808. Il doit s’agir d’un proxy direct HTTP/HTTPS standard, et il ne doit pas utiliser 127.0.0.1.

​

Qui peut lier et synchroniser

Comme sur Overleaf Cloud, seul le propriétaire du projet peut lier un projet à un dépôt GitLab. Une fois le projet lié, chaque collaborateur disposant d’un accès en modification peut le synchroniser.

Action	Qui peut l’effectuer
Exporter un projet vers un nouveau dépôt GitLab	Le propriétaire du projet
Importer un dépôt GitLab dans un nouveau projet	Tout utilisateur, qui devient propriétaire du nouveau projet
Récupérer (pull), pousser (push) et fusionner un projet lié	Le propriétaire et les collaborateurs disposant d’un accès en modification
Délier un projet de son dépôt	Le propriétaire du projet

• Overleaf communique avec GitLab au moyen du compte GitLab de l’utilisateur qui synchronise : chaque collaborateur qui synchronise lie donc son propre compte GitLab et doit être autorisé à pousser sur la branche par défaut du dépôt.
• Les collaborateurs en lecture seule ne peuvent pas utiliser la synchronisation GitLab pour le projet.

​

Fonctionnement de la synchronisation avec GitLab

• Autorisations : les utilisateurs doivent être autorisés à pousser sur la branche par défaut du projet lié. Lorsque la branche par défaut est protégée et que l’utilisateur ne peut pas y pousser, Overleaf lui demande de contacter le propriétaire du projet, comme pour un dépôt auquel il n’a plus accès.
• Fusion : lorsqu’un projet a été modifié à la fois dans Overleaf et dans GitLab, Overleaf commite ses modifications dans une branche temporaire nommée overleaf-YYYY-MM-DD-HHMMSS et la fusionne au moyen d’une merge request, car GitLab ne dispose d’aucune API permettant de fusionner des branches sans en passer par une. Après la fusion, Overleaf supprime la branche temporaire et la merge request. Seuls les administrateurs et les propriétaires de projet peuvent supprimer des merge requests dans GitLab ; pour les autres utilisateurs, la merge request fusionnée reste donc dans le projet.
• Règles de fusion : Overleaf ne contourne jamais les règles de fusion du projet. Lorsque la merge request présente un conflit, ou nécessite une approbation ou un pipeline réussi, elle reste ouverte et Overleaf demande à l’utilisateur de la fusionner dans GitLab, puis de poursuivre la synchronisation.
• Pipelines : les commits provenant d’Overleaf déclenchent des pipelines comme n’importe quel autre commit. Si votre projet exécute des pipelines pour les merge requests et exige qu’ils réussissent, les fusions depuis Overleaf attendent leur résultat, comme décrit ci-dessus.

​

Q&A

Puis-je faire un push forcé sur la branche par défaut ?

Réponse : Veuillez laisser les push forcés désactivés sur la branche par défaut. C’est le comportement par défaut de GitLab : la branche par défaut d’un nouveau projet est protégée et personne ne peut y faire de push forcé. Overleaf peut reprendre une branche réécrite, mais la synchronisation GitLab est conçue pour une branche par défaut dont l’historique ne fait que croître.

Puis-je renommer la branche par défaut d'un projet lié ?

Réponse : Non. Overleaf continue de se synchroniser avec la branche à laquelle le projet a été lié, si bien que les synchronisations échouent dès que cette branche est renommée ou supprimée. Pour synchroniser avec une autre branche, déliez le projet, puis importez le dépôt dans un nouveau projet, qui utilisera la branche par défaut actuelle.