# 启用 GitLab 同步

### 开始使用

在你想与 GitLab 仓库同步的空间中，前往右上角的空间菜单，并选择 **与 Git 同步**。在提供程序列表中，选择 **GitLab Sync**，然后点击 **配置**.

<figure><img src="https://2111890564-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNkEGS7hzeqa35sMXQZ4X%2Fuploads%2FCZRMtOF5b7dArKJxbQV1%2FEnabling%20GitLab%20Sync%402x.png?alt=media&#x26;token=9e78da77-b61d-44a6-baa3-c219e5b96f85" alt="A GitBook screenshot showing GitLab Sync configuration options"><figcaption><p>GitLab 同步配置选项。</p></figcaption></figure>

### 生成并输入你的 API 访问令牌

你可以在 GitLab 用户设置中生成 API 访问令牌。

{% hint style="info" %}
GitLab 中有两种类型的访问令牌：项目令牌和个人令牌。请注意，为了使集成正常工作，你需要使用个人令牌，你可以在 GitLab 用户偏好设置菜单中生成该令牌。
{% endhint %}

确保为你的令牌启用以下访问权限：

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

如果你创建的令牌还附带了特定角色，也请确保它具有 `维护者` 或者 `管理员` 角色。

然后，在配置 GitLab 集成时，你可以将该令牌粘贴到 API 访问令牌字段中。

### 选择一个仓库和分支

选择你想与 GitBook 内容保持同步的仓库。

{% hint style="info" %}
**看不到你的仓库？** 创建 API 令牌时，确保你已设置正确的权限。
{% endhint %}

选择正确的仓库后，选择你希望将提交推送到并从中同步的分支。

{% hint style="warning" %}
对于许多 GitLab 仓库， `main` 分支可能会被自动设置为受保护。如果是这种情况，我们建议添加一个特定分支来同步你的内容。然后你可以将其合并到 `main` 中，并保持保护设置不变。
{% endhint %}

### 执行初始同步

首次同步时，你可以选择以下两个方向中的一个进行同步：

1. GitBook -> GitLab 将同步你空间中的内容 **到** 所选分支。如果你是从一个空仓库开始，并希望快速导入你的 GitBook 内容，这会非常适合。
2. GitLab -> GitBook 将同步你空间中的内容 **从** 所选分支。这非常适合你在仓库中已有 Markdown 内容并希望将其导入 GitBook 的情况。

### 编写并提交

你已经可以开始了。你会注意到，如果你的空间之前处于 [实时编辑](https://gitbook-v2-q67etdj25-gitbook.vercel.app/url/gitbook.com/docs/documentation/zh/collaboration/live-edits) 模式下，实时编辑现在已被锁定。这使得当你团队中的某个人合并一个时，GitBook 能够可靠地将内容同步到你的仓库。[ 变更请求](https://gitbook-v2-q67etdj25-gitbook.vercel.app/url/gitbook.com/docs/documentation/zh/collaboration/change-requests) 时，我们能够可靠地将内容同步到你的仓库。

当你在 GitBook 中编辑时，每次更改请求合并都会在你选定的 GitLab 分支中生成一次提交。

当你向 GitLab 提交时，每次提交都会作为历史提交同步到你的 GitBook 空间。