> 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 同步选择一个单独的分支。你可以将该分支合并到 `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 同步** 在 [空间页眉](/docs/documentation/zh/can-kao/gitbook-ui.md#space-header)中。从提供商列表中，点击 **GitLab 同步**，然后点击 **配置**.


---

# 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.