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

# 启用 GitHub 同步

将你的 GitHub 仓库与 GitBook 同步

本指南将引导你使用 GitHub 上的仓库设置你的 GitBook 站点。

<figure><img src="https://2111890564-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNkEGS7hzeqa35sMXQZ4X%2Fuploads%2Fgit-blob-6c33061b672738c3e7da914fa50e7424a87179e2%2FGit%20Sync%20-%20GitHub.png?alt=media" alt="A GitBook screenshot showing GitHub Sync configuration options"><figcaption><p>GitHub 同步配置选项。</p></figcaption></figure>

{% stepper %}
{% step %}

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

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

{% step %}

### 连接 GitHub

连接有权访问你要同步的仓库的 GitHub 账号。

{% hint style="warning" %}
如果您看到 **“潜在的重复账户”** 错误消息，则表示您的 GitHub 账户已关联到另一个 GitBook 用户账户。

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

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

更多信息，请参阅我们的 [故障排除页面](https://gitbook.com/docs/documentation/zh/docs-as-code/git-sync/troubleshooting.md#potential-duplicated-accounts-when-signing-in).
{% endhint %}
{% endstep %}

{% step %}

### 选择仓库和分支

在 **源代码仓库**下，选择包含文档的仓库。选择 GitBook 要同步的分支。如果该分支不存在，GitBook 会在首次同步时创建它。

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

{% step %}

### 选择初始同步方向

选择首次同步时的权威内容来源。如果仓库内容应替换 GitBook 内容，请选择 **反转同步方向** 。

{% hint style="warning" %}
**GitHub → GitBook 可能会替换你所在分区的内容。** GitBook 会用所选分支的内容替换该分区。如果存储库为空，或者由于最近的变更请求尚未导出而落后于 GitBook，那么该分区和已发布网站中的内容都会丢失。

每次设置 Git Sync 时，都需要选择同步方向；重新连接或重新创建现有连接时也不例外。开始同步前，请确认存储库、分支和同步方向。如果选择 GitHub → 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 中合并一个变更请求，即可将其更改提交到 GitHub。提交到 GitHub 的内容会同步回 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)中。然后在提供商列表中点击 **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 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-github-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.
