GitLab Synchronisation

Link your GitLab account, import or export a project, sync changes both ways and unlink.

Connect a project to a GitLab repository. Changes go both ways, and only when you click Sync: nothing syncs on its own.

An administrator has to turn on GitLab Synchronisation first.

​

Link your GitLab account

You do this once.

1. Open your account settings

   Click Account, then Account settings. Under Project synchronisation, find GitLab and click Link.

   

   GitLab in the account settings

2. Authorize on GitLab

   GitLab opens. Sign in if you are asked to, then authorize the application.

3. Check the link

   You are back in the account settings. A green message says your GitLab account is linked, and the button now says Unlink.

   

   Your GitLab account is linked

If your account is not linked yet, Import from GitLab and the GitLab card in the editor ask you to link it first. Click Link to your GitLab account. You also end up in the account settings, in a new tab if you started in the editor. Then go back and start again.

The prompt when your account is not linked

​

Import a repository

This creates a new project from a GitLab repository, already linked to it.

1. Open the import dialog

   On the projects page, click New project, then Import from GitLab.

   

   The New project menu

2. Choose the repository

   Click Import to Overleaf next to the repository. The list includes your repositories and those of your groups.

   

   Your GitLab repositories

3. Check the project

   The new project opens with the files of the repository.

   

   The imported project

​

Export a project to a new repository

This creates a repository from a project and links them. A project can only be linked this way or by importing: you cannot link it to a repository that already exists.

1. Open GitLab in the editor

   Open the project. In the left bar, click Integrations, then GitLab.

   

   The Integrations panel

2. Fill in the repository

   Choose the Owner, which can be you or one of your groups. When you pick a group, this field is called Organization. Repository Name starts as the project’s name. The description is optional, and Private is selected by default. Click Create a GitLab repository.

   

   Export Project to GitLab

   If the name is already taken, the dialog says Please check that the repository name is valid, and that you have permission to create the repository. Change the name and click the button again.

3. Check the link

   The dialog now says This project is linked to and names the repository.

   

   The project is linked

​

Sync

1. Open the sync dialog

   Open a linked project. In the left bar, click Integrations, then GitLab.

   Recent commits in GitLab lists what will come into the project.

   

   A new commit waiting in GitLab

2. Describe your changes

   If you changed something in the project, a commit message box appears. It is optional: when you leave it empty, the commit is called Updates from Overleaf.

   

   The commit message for your changes

3. Click Sync

   Click Sync. New commits from GitLab come into the project, and your changes go to the default branch of the repository. If both sides changed different things, they are merged for you.

4. Check the result

   The dialog shows No new commits in GitLab since last merge. and the commit message box is gone. The files in the editor and the commits on GitLab are up to date.

   

   Everything is in sync

​

If the same lines changed on both sides

The dialog says the changes could not be merged and names a new branch, overleaf-YYYY-MM-DD-HHMMSS, which holds your changes. Overleaf also opens a merge request from that branch on GitLab.

A conflict

1. Merge that branch into the default branch on GitLab or with Git. You can close the dialog in the meantime: it shows the same message when you open it again.
2. Click I have manually merged. Continue. The merged result comes into the project. If you click it before the branch is merged, the dialog stays as it is.
3. The branch stays on GitLab, unless you deleted it when merging. Delete it when you no longer need it.

The same dialog appears when the repository’s merge rules hold the merge request back, for example when it needs an approval, even if no lines conflict. Once the rule allows it, merge the merge request on GitLab and click I have manually merged. Continue. See How syncing works with GitLab.

​

Unlink a project

Do this when you no longer want the project to sync.

1. Click Unlink

   In the sync dialog, click Unlink.

2. Confirm

   Click Confirm. This only removes the link: the connection to a repository you own, which the warning mentions, is an option you have afterwards, not something that happens now.

   

   Confirm the unlink

3. Check the result

   The dialog now shows Export Project to GitLab. The project and the repository both keep their content. To sync again, export the project to a new repository, or import the repository into a new project.

​

Unlink your GitLab account

In Account settings, under GitLab, click Unlink, then Unlink again in the dialog.

Unlink your account

Your projects stay linked to their repositories. You cannot sync them until you link your account again.

For who can do what in a shared project, see Who can link and sync.