Synchronisation Gitea

Cette fonctionnalité est développée par ayaka-notes/ayakaleaf-pro. Elle est introduite dans la v6.3.2 en avant-première et sera officiellement publiée dans la v6.4.0 : sa configuration et son comportement peuvent donc encore évoluer. Vos retours nous sont précieux si vous rencontrez un problème.

La synchronisation Gitea fonctionne comme la synchronisation GitHub et la synchronisation GitLab : les utilisateurs lient leur compte Gitea, exportent des projets vers de nouveaux dépôts Gitea, importent des dépôts Gitea et synchronisent les modifications dans les deux sens. Elle fonctionne avec Gitea 1.23 ou ultérieur, sur gitea.com ou sur votre propre instance.

​

Configurer la synchronisation Gitea

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

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Créez une application OAuth2 sur votre instance Gitea, dans Settings → Applications → Manage OAuth2 applications (ou Site Administration → Integrations → Applications pour une application à l’échelle de l’instance) :

• Application name : par exemple Overleaf, que les utilisateurs voient lorsqu’ils l’autorisent
• Redirect URIs : ${OVERLEAF_SITE_URL}/user/gitea-sync/oauth2/callback
• Confidential client : coché

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

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

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

Overleaf demande tout ce dont une synchronisation a besoin au moment où l’utilisateur lie son compte, afin que les utilisateurs n’aient jamais à refaire la liaison pour une autorisation manquante :

Scope	Utilisé pour
write:repository	Les dépôts, leurs fichiers (y compris les workflows CI sous .gitea/workflows), les branches et les pull requests
write:user	La création d’un dépôt de l’utilisateur lors d’un export (Gitea l’exige sur POST /user/repos)
write:organization	La liste des organisations de l’utilisateur et la création d’un dépôt de l’une d’elles lors d’un export

Gitea affiche ces scopes lorsque l’utilisateur autorise l’application, et limite le jeton à ceux-ci.

Les jetons d’accès Gitea expirent au bout d’une heure ([oauth2] ACCESS_TOKEN_EXPIRATION_TIME). Overleaf les renouvelle grâce au jeton d’actualisation que Gitea émet avec eux, y compris lorsque Gitea invalide les jetons d’actualisation après usage (INVALIDATE_REFRESH_TOKENS = true), de sorte que les utilisateurs restent liés jusqu’à ce qu’ils délient leur compte ou révoquent l’application dans Gitea.

​

Votre instance Gitea

Définissez GITEA_SYNC_URL sur l’adresse web de votre instance, son ROOT_URL, celle que vous utilisez pour ouvrir les dépôts dans le navigateur. L’API REST en est déduite :

Variable	Valeur par défaut
GITEA_SYNC_URL	https://gitea.com
GITEA_SYNC_API_URL	${GITEA_SYNC_URL}/api/v1

Un Gitea servi sous un sous-chemin fonctionne également, par exemple GITEA_SYNC_URL=https://example.com/gitea. Ne définissez GITEA_SYNC_API_URL que si votre instance expose l’API ailleurs, par exemple derrière une passerelle d’API.

• Créez l’application OAuth2 sur l’instance définie dans GITEA_SYNC_URL : une application créée sur une autre instance ne fonctionne pas.
• GITEA_SYNC_URL correspond uniquement à l’adresse web. N’y ajoutez pas /api/v1 ni de chemin d’utilisateur ou d’organisation.
• Overleaf commite au moyen de l’API de fichiers de Gitea, qui nécessite l’éditeur web : laissez [repository.editor] activé (valeur par défaut).

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

Les comptes et projets liés appartiennent à l’instance avec laquelle ils ont été liés. Avant de faire pointer GITEA_SYNC_URL vers une autre instance, demandez aux utilisateurs de délier leur compte Gitea 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 à Gitea. Définissez la variable d’environnement suivante : GITEA_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 Gitea. 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 Gitea	Le propriétaire du projet
Importer un dépôt Gitea 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 Gitea au moyen du compte Gitea de l’utilisateur qui synchronise : chaque collaborateur qui synchronise lie donc son propre compte Gitea 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 Gitea pour le projet.
• Délier le compte dans Overleaf supprime son jeton ; Gitea ne dispose d’aucune API pour le révoquer, révoquez donc également l’autorisation dans Settings → Applications de Gitea si vous le souhaitez.

​

Fonctionnement de la synchronisation avec Gitea

• Autorisations : les utilisateurs doivent être autorisés à pousser sur la branche par défaut du dépôt lié. Lorsqu’une règle de protection de branche ne permet pas à l’utilisateur d’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 Gitea, Overleaf commite ses modifications dans une branche temporaire nommée overleaf-YYYY-MM-DD-HHMMSS et la fusionne au moyen d’une pull request avec le style de fusion par défaut du dépôt, car Gitea ne dispose d’aucune API permettant de fusionner des branches sans en passer par une. Après la fusion, Overleaf supprime la branche temporaire ; la pull request fusionnée reste dans le dépôt pour mémoire.
• Règles de fusion : Overleaf ne contourne jamais la protection de branche du dépôt. Lorsque la pull request présente un conflit, ou nécessite des approbations ou des vérifications d’état réussies, elle reste ouverte et Overleaf demande à l’utilisateur de la fusionner dans Gitea, puis de poursuivre la synchronisation.
• Workflows CI : Overleaf n’affiche pas les fichiers cachés tels que .gitea/workflows/ et les laisse tels quels dans le dépôt. Les commits provenant d’Overleaf déclenchent Gitea Actions comme n’importe quel autre commit.

​

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, par exemple au moyen d’une règle de protection de branche. Overleaf peut reprendre une branche réécrite, mais la synchronisation Gitea 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.

La synchronisation Gitea prend-elle en charge Git LFS ?

Réponse : Non. Les projets Overleaf ne prennent pas en charge Git Large File Storage. Les fichiers suivis par Git LFS apparaissent dans Overleaf sous forme de fichiers pointeurs LFS, et non avec leur contenu. Commitez plutôt les images et les PDF directement dans le dépôt.

Fonctionne-t-elle avec les dépôts SHA-256 ?

Réponse : Pas encore. Overleaf compare les fichiers par leurs identifiants SHA-1 : dans un dépôt créé avec le format d’objet SHA-256, chaque récupération réécrit donc tous les fichiers, même ceux qui n’ont pas changé. Rien n’est perdu, mais veuillez utiliser le format SHA-1 par défaut.

Fonctionne-t-elle avec Forgejo ?

Réponse : La synchronisation Gitea est conçue et testée uniquement avec Gitea.