> 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/docs-as-code/git-sync/enabling-gitlab-sync.md).

# 启用 GitLab 同步

将你的 GitLab 仓库与 GitBook 同步

本指南将带你完成将 GitBook 站点与 GitLab 上的仓库进行设置。

<figure><img src="https://2111890564-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNkEGS7hzeqa35sMXQZ4X%2Fuploads%2Fgit-blob-5567051332191472a683f95cb7edab1f8738eba3%2FGit%20Sync%20-%20GitLab.png?alt=media" 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" %}
如果令牌有角色，请选择 `Maintainer` 或 `Admin`.
{% 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 可能会替换您网站的内容。** GitBook 会将每个已同步的分区替换为所选分支中的内容。如果存储库为空，或者由于最近的变更请求尚未导出而落后于 GitBook，那么这些内容将从该分区和已发布的网站中丢失。

每次设置 Git Sync 时，您都需要选择同步方向，包括重新连接或重新创建现有连接时。开始同步前，请确认存储库、分支和同步方向。如果选择 GitLab → GitBook，请检查该分支的最新提交是否包含您最近合并的变更请求。

如果内容已被替换，请参阅 [故障排除](https://gitbook.com/docs/documentation/zh/docs-as-code/git-sync/troubleshooting.md) 以将其恢复。
{% endhint %}
{% endstep %}

{% step %}

### 设置项目目录

如果你的文档位于子目录中，请在以下位置填写该目录： **项目目录**。GitBook 会将你的网站 `gitbook-docs.yaml` 文件存储在此目录中。如果你的文档位于 [单体仓库](https://gitbook.com/docs/documentation/zh/docs-as-code/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 Sync，请在要同步的空间中点击 **设置** 旁边的 **Git Sync** （位于 [空间标题栏](https://gitbook.com/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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://gitbook.com/docs/documentation/zh/docs-as-code/git-sync/enabling-gitlab-sync.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
