# Enabling GitLab Sync

### Getting started

In the space you want to sync with your GitLab repo, head to the space menu in the top right, and select **Synchronize with Git**. From the provider list, select **GitLab Sync**, and click **Configure**.

<figure><img src="/files/Srm9GX4G9hYZw5UQ6y4y" alt="A GitBook screenshot showing GitLab Sync configuration options"><figcaption><p>GitLab Sync configuration options.</p></figcaption></figure>

### Generate and enter your API access token

You can generate an API access token in your GitLab user settings.

{% hint style="info" %}
There are two types of access tokens in GitLab: Project and Personal. Note that in order for the integration to work you’ll need to use a Personal token, which you can generate from your GitLab user preferences menu.
{% endhint %}

Ensure that you enable the following access for your token:

* `api`
* `read_repository`
* `write_repository`

If the tokens you create also have a specific role attached to them, also make sure that it has a `Maintainer` or `Admin` role.

Then you can paste the token into the API access token field when configuring your GitLab integration.

### Select a repository and branch

Select the repository you want to keep in sync with your GitBook content.

{% hint style="info" %}
**Can’t see your repository?** Ensure you’ve set the correct permissions when creating your API token.
{% endhint %}

Once you’ve selected the correct repository, choose which branch you want commits to be pushed to and synced from.

{% hint style="warning" %}
For many GitLab repositories, the `main` branch might be automatically set to protected. If this is the case, we recommend adding a specific branch to sync your content between. You can then merge this into `main` and keep the protection in place.
{% endhint %}

### Perform an initial sync

When syncing for the first time, you’ll have the option to sync in one of two directions:

1. GitBook -> GitLab will sync your space’s content **to** the selected branch. This is great if you’re starting from an empty repository and want to get your GitBook content in quickly.
2. GitLab -> GitBook will sync your space’s content **from** the selected branch. This is great if you have existing markdown content in a repository and want to bring it into GitBook.

### Write and commit

You’re good to go. You’ll notice that if your space was in [live edit](/docs/collaboration/live-edits.md) mode, live edits are now locked. This allows GitBook to reliably sync content to your repository when someone in your team merges a[ change request](/docs/collaboration/change-requests.md) in GitBook.

When you edit on GitBook, every change request merge will result in a commit to your selected GitLab branch.

When you commit to GitLab, every commit will be synced to your GitBook space as a history commit.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://gitbook.com/docs/getting-started/git-sync/enabling-gitlab-sync.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.