> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Synchronisation

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

> [!NOTE]
>
> This feature is developed by [ayaka-notes/ayakaleaf-pro](https://github.com/ayaka-notes/ayakaleaf-pro), modified by [yu-i-i/overleaf-cep](https://github.com/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.

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-36.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=fd5305cbb4ea8505b5eab6f41f90a57c)

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-39.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=1d8103102915872ba94119bb00fa58e0)

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-35.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=18c0d0917b5c3768593a608a53b6c19c)

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-40.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=7ebf71a5528a1b22e1e2c7f17a71b49a)

### Setup GitHub Synchronisation

> [!WARNING]
>
> You need to enable [git-bridge](https://ayakaleaf-pro.mintlify.site/on-premises/configuration/overleaf-toolkit/integrations/git-integration.md) first before using GitHub Synchronisation.
>
> ```dotenv title="config/overleaf.rc" theme={null}
> GIT_BRIDGE_ENABLED=true
> ```

Visit [developers settings](https://github.com/settings/developers) 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.

```dotenv title="config/variables.env" wrap theme={null}
# 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
```

> [!WARNING]
>
> 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.

> [!WARNING]
>
> `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.

> [!WARNING]
>
> 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

> [!NOTE]
>
> 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.

```dotenv title="config/variables.env" wrap theme={null}
# 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` |

> [!WARNING]
>
> * 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.

> [!NOTE]
>
> 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`.

> [!CAUTION]
>
> 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

> [accordion] 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**.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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`.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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](https://ayakaleaf-pro.mintlify.site/on-premises/configuration/overleaf-toolkit/integrations/git-integration.md)) and recreate the container. The Toolkit already sets this value; check that `docker-compose.override.yml` does not override it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.