GitHub Synchronisation

Let users sync their projects with GitHub or GitHub Enterprise repositories.

This feature is developed by ayaka-notes/ayakaleaf-pro, modified by yu-i-i/overleaf-cep. It is introduced from v6.2.0 and later. It’s still in beta status. We need your feedback if you have any problem.

Setup GitHub Synchronisation

You need to enable git-bridge first before using GitHub Synchronisation.

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Visit developers settings to create your GitHub OAuth application, and copy your CLIENT_ID and SECRET.

Notes: when you create the OAuth App, enter ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback in Authorization callback URL. Ayakaleaf Pro builds the same address from OVERLEAF_SITE_URL, so there is nothing to set for it in config/variables.env.

Then, add the following settings to your overleaf env var files.

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

Before configuring the GitHub OAuth callback URL, make sure OVERLEAF_SITE_URL is set correctly.

If you are in a region with restricted network access, you may need to configure a proxy to access GitHub. Set the following environment variable: GITHUB_SYNC_PROXY_URL=http://10.0.0.1:10808. Please make sure your use of a proxy complies with local laws and regulations.

GITHUB_SYNC_PROXY_URL must be a standard HTTP/HTTPS forward proxy (e.g. the HTTP port of Clash). GitHub download mirrors such as gh-proxy.org are not supported.

Do not use 127.0.0.1 for proxy host. If the proxy is running on host server, use the server’s LAN IP (like 192.168.1.xx) address and make sure the proxy is configured to accept connections from devices on the local network.

GitHub Enterprise

GitHub Enterprise support is introduced from v6.3.1 and later. Earlier versions only connect to github.com, and the variables below have no effect.

By default GitHub Synchronisation connects to github.com. To use GitHub Enterprise Server (self-hosted) or GitHub Enterprise Cloud with data residency (GHE.com), set GITHUB_SYNC_URL to the web address of your instance, the one you open repositories with in the browser.

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

The REST and GraphQL API endpoints are derived from GITHUB_SYNC_URL the same way as the GitHub CLI does:

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

Only set the API endpoints when your instance serves them somewhere else, for example behind an API gateway:

Variable	Default
GITHUB_SYNC_URL	https://github.com
GITHUB_SYNC_API_URL	Derived from GITHUB_SYNC_URL, see the table above
GITHUB_SYNC_GRAPHQL_URL	Derived from GITHUB_SYNC_API_URL when it is set (/api/v3 becomes /api/graphql, otherwise /graphql is appended), else from GITHUB_SYNC_URL

• Create the OAuth application on your enterprise instance (Settings → Developer settings → OAuth Apps), an application from github.com does not work there. The callback URL is the same: ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback.
• GITHUB_SYNC_URL is the web address only. Do not set it to an API address such as https://api.github.com or https://HOST/api/v3, and do not add an organisation path.
• All three addresses must point to the same GitHub instance.

If your instance uses a certificate from a private CA, mount the CA certificate into the container and point NODE_EXTRA_CA_CERTS at it, e.g. NODE_EXTRA_CA_CERTS=/var/lib/overleaf/certs/github-ca.pem.

Linked accounts and projects belong to the instance they were linked with. Before switching GITHUB_SYNC_URL to another instance, ask users to unlink their GitHub account and projects.

Who can link and sync

Like on Overleaf Cloud, only the project owner can link a project to a GitHub repository. Once it is linked, every collaborator with edit access can sync it.

Action	Who can do it
Export a project to a new GitHub repository	The project owner
Import a GitHub repository into a new project	Any user, who becomes the owner of the new project
Pull, push and merge a linked project	The owner and collaborators with edit access
Unlink a project from its repository	The project owner

• Overleaf talks to GitHub with the GitHub account of the user who syncs, so every collaborator who syncs links their own GitHub account, and needs to be allowed to push to the default branch of the repository.
• View-only collaborators cannot use GitHub Synchronisation for the project.

Q&A

How do I link a project to GitHub and sync it?

Answer: In the editor, open Integrations and click GitHub. If your GitHub account is not linked yet, click Link to your GitHub account first. In Export Project to GitHub, enter a repository name, choose Private under Repository visibility, and click Create a GitHub repository.

After that, the same card opens Sync with GitHub, which lists the new commits in GitHub. Click Sync to commit your Overleaf changes to the default branch and bring the GitHub changes into the project. Syncing goes both ways but only runs when someone clicks Sync; there is no scheduled sync. When both sides changed, Overleaf merges through a temporary branch named overleaf-YYYY-MM-DD-HHMMSS. If that merge has a conflict, merge the branch in GitHub yourself, then click I have manually merged. Continue.

Can I force push to the default branch?

Answer: We do not recommend it. Overleaf detects a force push, warns about it and takes over the rewritten branch, merging the changes made in Overleaf since the last sync. To avoid surprises, protect the default branch against force pushes in the repository settings.

Can I rename the default branch of a linked project?

Answer: Please do not. Overleaf keeps syncing with the branch the project was linked to. To sync with another branch, unlink the project, then import the repository into a new project, which uses the current default branch.

GitHub sync shows "Something wrong with GitHub request"

Answer: This message means the server could not reach GitHub, for example because of a network, DNS, TLS or proxy problem. Run bin/logs web to see the full error. If the server needs a proxy to reach GitHub, set GITHUB_SYNC_PROXY_URL.

Should I disable "Expire user access tokens" in the GitHub OAuth App?

Answer: Yes. GitHub sync does not renew expired tokens. With expiring tokens enabled, users have to connect GitHub again each time their token expires.

Does my instance need to be reachable from the internet?

Answer: No. Linking an account goes through the user’s browser, so the OAuth callback address only needs to open in the user’s browser. The server only needs to reach GitHub; if it needs a proxy for that, set GITHUB_SYNC_PROXY_URL. GitHub never calls your instance: a project is synced only when a user syncs it in the editor.

Linking my GitHub account fails or sends me back without linking

Answer: Check these in order:

• Open Overleaf at the exact address set in OVERLEAF_SITE_URL. GitHub sends you back to ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback, and your login only exists on the address you started from, so another host, IP or port ends on the login page or on “Restricted, sorry you don’t have permission to load this page”.
• The Authorization callback URL of the OAuth App must be ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback, with the same scheme, host and port.
• An error page with Failed to obtain access token from Git server means GitHub did not return a token: check GITHUB_SYNC_CLIENT_ID and GITHUB_SYNC_CLIENT_SECRET, and that the server can reach GitHub. Run bin/logs web to see the full error.

After changing config/variables.env, run bin/up to recreate the containers.

Importing a repository fails with "EmptyZipFileError: empty_zip_file" or "unzip failed"

Answer: Overleaf imports the zip archive of the latest commit on the repository’s default branch, and this error means that archive has no file Overleaf can import. Check the default branch on GitHub:

• It contains the project files, not only files Overleaf skips on import: dotfiles such as .gitignore and .gitmodules (.latexmkrc is kept), and build files such as *.aux, *.log, *.bbl, *.synctex.gz, *.doc and *.docx.
• The files are not only inside Git submodules. GitHub’s archive leaves submodules as empty folders.
• The files you expect are on the default branch, not on another branch. Import always uses the default branch.

Importing a repository fails with "connect ECONNREFUSED" to "sharelatex:3054"

Answer: V1_HISTORY_URL is set to http://sharelatex:3054, a value older versions of these docs gave. Port 3054 is the project-history service, which only listens inside the container, while V1_HISTORY_URL must point to history-v1. Overleaf saves every binary file (images, PDFs) of the imported repository to history-v1, so the import fails; uploading such a file in the editor fails the same way. In your docker-compose.yml, set V1_HISTORY_URL: "http://sharelatex:3100/api" on the sharelatex service (see Git Integration) and recreate the container. The Toolkit already sets this value; check that docker-compose.override.yml does not override it.