> 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-github-sync.md).

# 启用 GitHub 同步

本指南将引导你通过在 GitHub 上的仓库来设置你的 GitBook 站点。

<figure><img src="/files/eb392d4939938058a36ab8fd96adf0f494018b82" alt="A GitBook screenshot showing GitHub Sync configuration options"><figcaption><p>GitHub Sync 配置选项。</p></figcaption></figure>

{% stepper %}
{% step %}

### 为你的站点打开 Git Sync

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

{% step %}

### 连接 GitHub

连接拥有你想要同步的仓库访问权限的 GitHub 账户。

{% hint style="warning" %}
如果你在这一步看到 **“可能重复的账户”** 错误信息，这意味着你的 GitHub 账户已经与另一个 GitBook 用户账户关联。

为了帮助你识别哪些账户已关联，你需要退出当前会话，并使用“使用 GitHub 登录”方式重新登录。

如果你已经知道与 GitHub 关联的 GitBook 账户，可以先登录该用户账户并解除关联你的 GitHub 账户（在设置中完成），然后再重新登录并关联你当前的账户。

了解更多，请查看我们的 [故障排查页面](/docs/documentation/zh/wen-dang-ji-dai-ma/git-sync/troubleshooting.md#potential-duplicated-accounts-when-signing-in).
{% endhint %}
{% endstep %}

{% step %}

### 选择仓库和分支

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

{% hint style="info" %}
**找不到你的仓库？** 如果你在列表中找不到你的仓库，请确保你已安装 [GitBook GitHub 应用](https://github.com/apps/gitbook-com) 并且作用域正确（即你的个人账户或该仓库所在的 GitHub 组织）。你还应检查是否在 GitBook GitHub 应用中配置了正确的仓库访问权限。
{% endhint %}
{% endstep %}

{% step %}

### 选择初始同步方向

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

{% hint style="warning" %}
**GitHub → GitBook 可以替换你版块的内容。** 如果你选择一个空仓库，GitBook 可以用该仓库的空内容替换你的版块。

在开始初始同步之前，请确认仓库、分支和方向。确保目标内容可以安全替换。
{% endhint %}
{% endstep %}

{% step %}

### 设置项目目录

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

{% step %}

### 映射你的空间

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

{% step %}

### 查看高级选项

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

{% step %}

### 同步你的站点

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

{% step %}

### 写入并提交

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

#### 从站点级 Git Sync 中排除某个空间

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

如果该站点已经使用 Git Sync，GitBook 会要求你选择一个范围：

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

如果该站点未使用 Git Sync，GitBook 会为该空间单独配置 Git Sync。

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

{% hint style="warning" %}
驱动我们 GitHub 集成的 GitHub 应用目前对 GitHub Enterprise Server 实例上的客户不可用。
{% endhint %}


---

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