# 启用 GitHub 同步

### 开始使用

在你想要与 GitHub 仓库同步的空间中，前往 [空间标题](https://gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs/documentation/zh/zi-yuan/gitbook-ui#space-header) 在右上角，然后选择 **配置**。在提供程序列表中，选择 **GitHub 同步**.

<figure><img src="https://2111890564-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNkEGS7hzeqa35sMXQZ4X%2Fuploads%2FSmP9bdDqDK0gOpDYdSdj%2FEnabling%20GitHub%20Sync%402x.png?alt=media&#x26;token=a10a9f24-4f69-4b34-a802-64424aac7f76" alt="A GitBook screenshot showing GitHub Sync configuration options"><figcaption><p>GitHub 同步配置选项。</p></figcaption></figure>

### 通过 GitHub 进行身份验证

如果你是第一次设置 GitHub 同步，并且还没有关联 GitHub 账户，那么在你开始配置 Git 同步时，系统会提示你这样做。如果你已经关联了账户，你可能仍然需要通过 GitHub 进行身份验证。

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

为了帮助你识别哪些账户已关联，你需要先退出当前会话，然后使用通过 GitHub 登录的方法重新登录。

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

在我们的 [故障排除页面](https://gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs/documentation/zh/getting-started/troubleshooting#potential-duplicated-accounts-when-signing-in).
{% endhint %}

### 将 GitBook 应用安装到你的 GitHub 账户

如果你还没有这样做，你会看到一个提示，要求将 [GitBook 应用](https://github.com/apps/gitbook-com) 添加到你的 GitHub 账户。

按照 GitHub 弹出窗口中的说明操作，并根据你的需求，授予 GitBook 特定仓库权限，或允许访问所有仓库。

### 选择一个仓库和分支

选择你想要与 GitBook 内容保持同步的账户和仓库。

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

选择正确的仓库后，选择你希望将提交推送到并从中同步的分支。

### 执行初始同步

首次同步时，你可以选择以下两个方向中的一个进行同步：

1. GitBook -> GitHub 将同步你空间的内容 **到** 所选分支。如果你是从一个空仓库开始，并希望快速导入你的 GitBook 内容，这会非常适合。
2. GitHub -> GitBook 将同步你空间的内容 **从** 所选分支。如果你的仓库中已有 Markdown 内容，并且希望将其导入 GitBook，这会非常适合。

### 编写并提交

你已经可以开始了。你会注意到，如果你的空间之前处于 [实时编辑](https://gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs/documentation/zh/collaboration/live-edits) 模式，那么实时编辑现在已被锁定。这样可以确保当你团队中的某个人在 GitBook 中合并一个[ 变更请求](https://gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs/documentation/zh/collaboration/change-requests) 时，我们能够可靠地将内容同步到你的仓库。

当你在 GitBook 中编辑时，每次合并变更请求都会向你所选的 GitHub 分支生成一次提交。

当你向 GitHub 提交时，每次提交都会作为历史提交同步到你的 GitBook 空间。

{% hint style="warning" %}
为我们的 GitHub 集成提供支持的 GitHub 应用目前不适用于使用 GitHub Enterprise Server 实例的客户。
{% endhint %}