> ## 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.

# GitLab Synchronisation

<Info>
  This feature is developed by [ayaka-notes/ayakaleaf-pro](https://github.com/ayaka-notes/ayakaleaf-pro). It is introduced from v6.4.0 and later. It's still in beta status. We need your feedback if you have any problem.
</Info>

GitLab Synchronisation works like [GitHub Synchronisation](/on-premises/configuration/overleaf-toolkit/github-synchronisation): users link their GitLab account, export projects into new GitLab projects, import GitLab repositories, and sync changes in both directions. It works with GitLab.com and with self-managed GitLab 15.10 or later (Community and Enterprise Edition).

### Setup GitLab Synchronisation

<Warning>
  You need to enable [git-bridge](/on-premises/configuration/overleaf-toolkit/git-integration) first before using GitLab Synchronisation.

  ```dotenv title="config/overleaf.rc" theme={null}
  GIT_BRIDGE_ENABLED=true
  ```
</Warning>

Create an OAuth application on your GitLab instance, under *User settings → Applications* (or *Admin area → Applications* for an instance-wide application):

* **Redirect URI**: `${OVERLEAF_SITE_URL}/user/gitlab-sync/oauth2/callback`
* **Confidential**: checked
* **Scopes**: `api`

Copy the **Application ID** and the **Secret**, 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 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
```

<Warning>
  Before configuring the GitLab OAuth redirect URI, make sure `OVERLEAF_SITE_URL` is set correctly.
</Warning>

GitLab access tokens expire after two hours. Overleaf refreshes them with the refresh token GitLab issues along with them, so users stay linked until they unlink or revoke the application in GitLab.

### Self-managed GitLab

Set `GITLAB_SYNC_URL` to the web address of your instance, the one you open projects with in the browser. The REST API is derived from it:

| Variable | Default |
| - | - |
| `GITLAB_SYNC_URL` | `https://gitlab.com` |
| `GITLAB_SYNC_API_URL` | `${GITLAB_SYNC_URL}/api/v4` |

Only set `GITLAB_SYNC_API_URL` when your instance serves the API somewhere else, for example behind an API gateway.

<Warning>
  * Create the OAuth application on the instance you set in `GITLAB_SYNC_URL`, an application from `gitlab.com` does not work on a self-managed instance.
  * `GITLAB_SYNC_URL` is the web address only. Do not add `/api/v4` or a group path.
</Warning>

<Info>
  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/gitlab-ca.pem`.
</Info>

<Danger>
  Linked accounts and projects belong to the instance they were linked with. Before switching `GITLAB_SYNC_URL` to another instance, ask users to unlink their GitLab account and projects.
</Danger>

If you are in a region with restricted network access, you may need to configure a proxy to access GitLab. Set the following environment variable: `GITLAB_SYNC_PROXY_URL=http://10.0.0.1:10808`. It must be a standard HTTP/HTTPS forward proxy, and must not use `127.0.0.1`.

### Who can link and sync

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

| Action | Who can do it |
| - | - |
| Export a project to a new GitLab repository | The project owner |
| Import a GitLab 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 GitLab with the GitLab account of the user who syncs, so every collaborator who syncs links their own GitLab account, and needs to be allowed to push to the default branch of the repository.
* View-only collaborators cannot use GitLab Synchronisation for the project.

### How syncing works with GitLab

* **Permissions**: users need to be allowed to push to the default branch of the linked project. When the default branch is protected and the user may not push to it, Overleaf asks them to contact the project owner, as with a repository they lost access to.
* **Merging**: when a project changed both in Overleaf and in GitLab, Overleaf commits its changes to a temporary branch named `overleaf-YYYY-MM-DD-HHMMSS` and merges it through a merge request, because GitLab has no API to merge branches without one. After the merge, Overleaf deletes the temporary branch and the merge request. Only administrators and project owners may delete merge requests in GitLab, so for other users the merged merge request stays in the project.
* **Merge rules**: Overleaf never bypasses the project's merge rules. When the merge request has a conflict, or needs an approval or a passing pipeline, it stays open and Overleaf asks the user to merge it in GitLab, then to continue syncing.
* **Pipelines**: commits from Overleaf start pipelines like any other commit. If your project runs pipelines for merge requests and requires them to pass, merges from Overleaf wait for them, as described above.

### Q\&A

<Accordion title="Can I force push to the default branch?">
  <strong>Answer:</strong> Please keep force pushes to the default branch disabled. This is GitLab's default: the default branch of a new project is protected and no one can force push to it. Overleaf can take over a rewritten branch, but GitLab Synchronisation is designed for a default branch whose history only grows.
</Accordion>

<Accordion title="Can I rename the default branch of a linked project?">
  <strong>Answer:</strong> No. Overleaf keeps syncing with the branch the project was linked to, so syncs fail once that branch is renamed or removed. To sync with another branch, unlink the project, then import the repository into a new project, which uses the current default branch.
</Accordion>


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