> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/zh/wen-dang-ji-dai-ma/git-sync/enabling-gitlab-sync.md).

# 启用 GitLab 同步

本指南将带你完成使用 GitLab 上的仓库设置 GitBook 站点的过程。

<figure><img src="/files/0e4ac13633fd98487f07d9917cd764541a9b9af6" alt="A GitBook screenshot showing GitLab Sync configuration options"><figcaption><p>GitLab 同步配置选项。</p></figcaption></figure>

{% stepper %}
{% step %}

### 为你的站点打开 Git 同步

在你的站点中，从侧边栏打开 Git 同步。
{% endstep %}

{% step %}

### 连接 GitLab

在你的 GitLab 用户设置中创建一个个人访问令牌。启用 `api`, `read_repository`，以及 `write_repository`，然后在 GitBook 中输入该令牌。

{% hint style="info" %}
如果你的令牌具有角色，请选择 `维护者` 或 `管理`.
{% endhint %}
{% endstep %}

{% step %}

### 选择仓库和分支

在 **源仓库**，选择包含你文档的仓库。选择 GitBook 要同步的分支。如果该分支不存在，GitBook 会在初始同步期间创建它。

{% hint style="info" %}
**找不到你的仓库？** 确保你的个人访问令牌具有所需的权限范围和仓库访问权限。
{% endhint %}

{% hint style="warning" %}
如果你的 `main` 分支受保护，请为 Git Sync 选择一个单独的分支。你可以将该分支合并到 `main` 同时保留其保护设置。
{% endhint %}
{% endstep %}

{% step %}

### 选择初始同步方向

为初始同步选择事实来源。选择 **切换方向** ，如果仓库内容应替换 GitBook 内容。

{% hint style="warning" %}
**GitLab → GitBook 可以替换你网站的内容。** 在开始同步之前，请确认仓库、分支和方向。确保目标内容可以安全替换。
{% endhint %}
{% endstep %}

{% step %}

### 设置项目目录

如果你的文档位于子目录中，请在 **项目目录**下输入它。GitBook 会将你站点的 `docs.yaml` 文件存储在此目录中。如果你的文档位于一个 [monorepo](/docs/documentation/zh/wen-dang-ji-dai-ma/git-sync/monorepos.md).
{% endstep %}

{% step %}

### 映射你的空间

在 **内容映射**，将每个空间分配到仓库中的一个目录。对于相对于项目目录的路径，请使用 `./` 。对于来自仓库根目录的路径，请使用 `/` 。新关联的空间会自动同步。
{% endstep %}

{% step %}

### 查看高级选项

如有需要，可配置代理指令文件、提交消息模板或 fork 预览。
{% endstep %}

{% step %}

### 同步你的站点

点击 **同步** 以开始初始同步。
{% endstep %}

{% step %}

### 写入并提交

在 GitBook 中合并变更请求，将其更改提交到 GitLab。对 GitLab 的提交会同步回 GitBook。
{% endstep %}
{% endstepper %}

#### 从站点级 Git 同步中排除一个空间

在该站点的 Git 同步内容映射中，点击你要排除的空间旁边的移除图标。然后你就可以从该空间配置 Git 同步。

如果该站点已经使用 Git 同步，GitBook 会让你选择一个范围：

* 选择该站点的仓库和分支，将该空间添加到站点级 Git 同步中。
* 选择一个独立的仓库和分支来配置空间 Git 同步。

如果该站点不使用 Git 同步，GitBook 会为该空间独立配置 Git 同步。

要为单个空间配置 Git 同步，在你要同步的空间中，点击 **设置** 旁边的 **Git Sync** 中启用 [空间标题](/docs/documentation/zh/can-kao/gitbook-ui.md#space-header)。在提供方列表中，点击 **GitLab Sync**，并点击 **配置**.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://gitbook.com/docs/documentation/zh/wen-dang-ji-dai-ma/git-sync/enabling-gitlab-sync.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.