Enabling GitLab Sync

Sync your GitLab repo with GitBook

This guide will take you through setting up your GitBook site with a repo on GitLab.

GitLab Sync configuration options.

1

Open Git Sync for your site

From your site, open Git Sync in the sidebar.

2

Connect GitLab

Create a Personal access token in your GitLab user settings. Enable api, read_repository, and write_repository, then enter the token in GitBook.

If your token has a role, select Maintainer or Admin.

3

Select a repository and branch

Under Source repository, select the repository that contains your documentation. Select the branch that GitBook syncs with. If the branch doesn’t exist, GitBook creates it during the initial sync.

Can’t find your repository? Make sure your Personal access token has the required scopes and repository access.

If your main branch is protected, select a separate branch for Git Sync. You can merge that branch into main while keeping its protection.

4

Choose an initial sync direction

Choose the source of truth for the initial sync. Select Swap direction if the repository content should replace the GitBook content.

GitLab → GitBook can replace your site’s content. Before you start the sync, confirm the repository, branch, and direction. Make sure the destination content is safe to replace.

5

Set the project directory

If your documentation lives in a subdirectory, enter it under Project directory. GitBook stores your site’s docs.yaml file in this directory. Use this configuration if your docs live within a monorepo.

6

Map your spaces

Under Content mapping, assign each space to a directory in the repository. Use ./ for paths relative to the project directory. Use / for paths from the repository root. Newly linked spaces sync automatically.

7

Review advanced options

If needed, configure agent instruction files, a commit message template, or fork previews.

8

Sync your site

Click Sync to start the initial sync.

9

Write and commit

Merge a change request in GitBook to commit its changes to GitLab. Commits to GitLab sync back to GitBook.

Exclude a space from site-wide Git Sync

In the site’s Git Sync content mapping, click the remove icon next to the space you want to exclude. You can then configure Git Sync from that space.

If the site already has Git Sync, GitBook asks you to choose a scope:

• Select the site’s repository and branch to add the space to site-wide Git Sync.
• Select an independent repository and branch to configure Space Git Sync.

If the site doesn’t use Git Sync, GitBook configures Git Sync independently for the space.

To configure Git Sync for a single space, in the space you want to sync, click Set up next to Git Sync in the space header. From the provider list, click GitLab Sync, and click Configure.