Synchronisation GitHub

Permettez aux utilisateurs de synchroniser leurs projets avec des dépôts GitHub ou GitHub Enterprise.

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

​

Configurer la synchronisation GitHub

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

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Rendez-vous dans les paramètres développeur pour créer votre application OAuth GitHub, puis copiez votre CLIENT_ID et votre SECRET.

Remarque : lors de la création de l’OAuth App, saisissez ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback dans Authorization callback URL. Ayakaleaf Pro construit la même adresse à partir de OVERLEAF_SITE_URL ; il n’y a donc rien à définir pour elle dans config/variables.env.

Ajoutez ensuite les paramètres suivants à vos fichiers de variables d’environnement Overleaf.

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

Avant de configurer l’URL de rappel OAuth de GitHub, assurez-vous que OVERLEAF_SITE_URL est correctement défini.

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 à GitHub. Définissez la variable d’environnement suivante : GITHUB_SYNC_PROXY_URL=http://10.0.0.1:10808. Veillez à ce que votre utilisation d’un proxy soit conforme aux lois et réglementations locales.

GITHUB_SYNC_PROXY_URL doit être un proxy direct HTTP/HTTPS standard (par exemple le port HTTP de Clash). Les miroirs de téléchargement GitHub tels que gh-proxy.org ne sont pas pris en charge.

N’utilisez pas 127.0.0.1 comme hôte du proxy. Si le proxy s’exécute sur le serveur hôte, utilisez l’adresse IP du serveur sur le réseau local (par exemple 192.168.1.xx) et assurez-vous que le proxy est configuré pour accepter les connexions des appareils du réseau local.

​

GitHub Enterprise

La prise en charge de GitHub Enterprise est disponible à partir de la v6.3.1. Les versions antérieures se connectent uniquement à github.com, et les variables ci-dessous n’ont aucun effet.

Par défaut, la synchronisation GitHub se connecte à github.com. Pour utiliser GitHub Enterprise Server (auto-hébergé) ou GitHub Enterprise Cloud avec résidence des données (GHE.com), définissez GITHUB_SYNC_URL sur l’adresse web de votre instance, celle que vous utilisez pour ouvrir les dépôts dans le navigateur.

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

Les points de terminaison des API REST et GraphQL sont déduits de GITHUB_SYNC_URL de la même manière que le fait GitHub CLI :

GITHUB_SYNC_URL	API REST	API GraphQL
https://github.com (par défaut)	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 (tout autre)	https://HOST/api/v3	https://HOST/api/graphql

Ne définissez les points de terminaison de l’API que si votre instance les expose ailleurs, par exemple derrière une passerelle d’API :

Variable	Valeur par défaut
GITHUB_SYNC_URL	https://github.com
GITHUB_SYNC_API_URL	Déduite de GITHUB_SYNC_URL, voir le tableau ci-dessus
GITHUB_SYNC_GRAPHQL_URL	Déduite de GITHUB_SYNC_API_URL lorsqu’elle est définie (/api/v3 devient /api/graphql, sinon /graphql est ajouté), sinon de GITHUB_SYNC_URL

• Créez l’application OAuth sur votre instance Enterprise (Settings → Developer settings → OAuth Apps) : une application créée sur github.com n’y fonctionne pas. L’URL de rappel est la même : ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback.
• GITHUB_SYNC_URL correspond uniquement à l’adresse web. Ne la définissez pas sur une adresse d’API telle que https://api.github.com ou https://HOST/api/v3, et n’y ajoutez pas de chemin d’organisation.
• Les trois adresses doivent pointer vers la même instance GitHub.

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

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

​

Qui peut lier et synchroniser

Comme sur Overleaf Cloud, seul le propriétaire du projet peut lier un projet à un dépôt GitHub. 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 GitHub	Le propriétaire du projet
Importer un dépôt GitHub 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 GitHub au moyen du compte GitHub de l’utilisateur qui synchronise : chaque collaborateur qui synchronise lie donc son propre compte GitHub 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 GitHub pour le projet.

​

Q&A

Comment lier un projet à GitHub et le synchroniser ?

Réponse : Dans l’éditeur, ouvrez Integrations et cliquez sur GitHub. Si votre compte GitHub n’est pas encore lié, cliquez d’abord sur Link to your GitHub account. Dans Export Project to GitHub, saisissez un nom de dépôt, choisissez Private sous Repository visibility, puis cliquez sur Create a GitHub repository.

Ensuite, la même carte ouvre Sync with GitHub, qui liste les nouveaux commits sur GitHub. Cliquez sur Sync pour committer vos modifications Overleaf sur la branche par défaut et intégrer les modifications GitHub dans le projet. La synchronisation fonctionne dans les deux sens, mais ne s’exécute que lorsque quelqu’un clique sur Sync ; il n’y a pas de synchronisation planifiée. Lorsque les deux côtés ont changé, Overleaf fusionne via une branche temporaire nommée overleaf-YYYY-MM-DD-HHMMSS. Si cette fusion présente un conflit, fusionnez vous-même la branche sur GitHub, puis cliquez sur I have manually merged. Continue.

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

Réponse : Nous ne le recommandons pas. Overleaf détecte un push forcé, émet un avertissement et reprend la branche réécrite, en fusionnant les modifications apportées dans Overleaf depuis la dernière synchronisation. Pour éviter les surprises, protégez la branche par défaut contre les push forcés dans les paramètres du dépôt.

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

Réponse : Veuillez ne pas le faire. Overleaf continue de se synchroniser avec la branche à laquelle le projet a été lié. 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 GitHub affiche « Something wrong with GitHub request »

Réponse : Ce message signifie que le serveur n’a pas pu joindre GitHub, par exemple en raison d’un problème de réseau, de DNS, de TLS ou de proxy. Exécutez bin/logs web pour voir l’erreur complète. Si le serveur a besoin d’un proxy pour joindre GitHub, définissez GITHUB_SYNC_PROXY_URL.

Dois-je désactiver « Expire user access tokens » dans l'OAuth App GitHub ?

Réponse : Oui. La synchronisation GitHub ne renouvelle pas les jetons expirés. Si les jetons à expiration sont activés, les utilisateurs doivent reconnecter GitHub chaque fois que leur jeton expire.

Mon instance doit-elle être accessible depuis Internet ?

Réponse : Non. La liaison d’un compte passe par le navigateur de l’utilisateur ; l’adresse de rappel OAuth doit donc seulement pouvoir s’ouvrir dans le navigateur de l’utilisateur. Le serveur doit uniquement pouvoir joindre GitHub ; s’il a besoin d’un proxy pour cela, définissez GITHUB_SYNC_PROXY_URL. GitHub n’appelle jamais votre instance : un projet n’est synchronisé que lorsqu’un utilisateur le synchronise dans l’éditeur.

La liaison de mon compte GitHub échoue ou me renvoie sans effectuer la liaison

Réponse : Vérifiez les points suivants dans l’ordre :

• Ouvrez Overleaf exactement à l’adresse définie dans OVERLEAF_SITE_URL. GitHub vous renvoie vers ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback, et votre session n’existe que sur l’adresse depuis laquelle vous avez commencé : un autre hôte, une autre IP ou un autre port aboutit à la page de connexion ou à « Restricted, sorry you don’t have permission to load this page ».
• L’Authorization callback URL de l’OAuth App doit être ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback, avec le même schéma, le même hôte et le même port.
• Une page d’erreur indiquant Failed to obtain access token from Git server signifie que GitHub n’a pas renvoyé de jeton : vérifiez GITHUB_SYNC_CLIENT_ID et GITHUB_SYNC_CLIENT_SECRET, ainsi que la capacité du serveur à joindre GitHub. Exécutez bin/logs web pour voir l’erreur complète.

Après avoir modifié config/variables.env, exécutez bin/up pour recréer les conteneurs.

L'import d'un dépôt échoue avec « EmptyZipFileError: empty_zip_file » ou « unzip failed »

Réponse : Overleaf importe l’archive zip du dernier commit de la branche par défaut du dépôt, et cette erreur signifie que cette archive ne contient aucun fichier qu’Overleaf peut importer. Vérifiez la branche par défaut sur GitHub :

• Elle contient les fichiers du projet, et pas seulement des fichiers qu’Overleaf ignore à l’import : les fichiers cachés (dotfiles) tels que .gitignore et .gitmodules (.latexmkrc est conservé), et les fichiers de compilation tels que *.aux, *.log, *.bbl, *.synctex.gz, *.doc et *.docx.
• Les fichiers ne se trouvent pas uniquement dans des sous-modules Git. L’archive de GitHub laisse les sous-modules sous forme de dossiers vides.
• Les fichiers attendus se trouvent sur la branche par défaut, et non sur une autre branche. L’import utilise toujours la branche par défaut.

L'import d'un dépôt échoue avec « connect ECONNREFUSED » vers « sharelatex:3054 »

Réponse : V1_HISTORY_URL est défini sur http://sharelatex:3054, une valeur donnée par d’anciennes versions de cette documentation. Le port 3054 est celui du service project-history, qui n’écoute qu’à l’intérieur du conteneur, alors que V1_HISTORY_URL doit pointer vers history-v1. Overleaf enregistre chaque fichier binaire (images, PDF) du dépôt importé dans history-v1 : l’import échoue donc, et le téléversement d’un tel fichier dans l’éditeur échoue de la même manière. Dans votre docker-compose.yml, définissez V1_HISTORY_URL: "http://sharelatex:3100/api" sur le service sharelatex (voir Intégration Git) et recréez le conteneur. Le Toolkit définit déjà cette valeur ; vérifiez que docker-compose.override.yml ne la remplace pas.