> ## Documentation Index
> Fetch the complete documentation index at: https://omer-914cc1c6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub

> 将文档与 GitHub 存储库同步

Mintlify 通过 GitHub 应用自动将文档与你的 GitHub 存储库保持同步。

<div id="installing-the-github-app">
  ## 安装 GitHub 应用
</div>

在拥有你文档存储库的 GitHub 账户或组织中安装 Mintlify GitHub 应用。你需要具备组织所有者身份，或在相应存储库中拥有管理员权限才能安装该应用。如果你没有所需权限，则需要由存储库所有者批准安装请求。

通过你的[控制台](https://dashboard.mintlify.com/settings/organization/github-app)安装 Mintlify GitHub 应用。

<Tip>
  我们建议仅向托管你文档的存储库授予访问权限。
</Tip>

<Frame>
  <img className="h-80" alt="Mintlify GitHub 应用安装页面，已选择“Only select repositories”选项。" src="https://mintcdn.com/omer-914cc1c6/1pfjDJXEL6HIHDKE/images/github/select-repos.png?fit=max&auto=format&n=1pfjDJXEL6HIHDKE&q=85&s=0aa6291d0b390f385e9f04dac9ec7218" width="2980" height="1702" data-path="images/github/select-repos.png" />
</Frame>

<div id="permissions">
  ## 权限
</div>

安装 GitHub 应用时，你会被提示授予以下权限：

读取权限：

* `metadata`: 基本存储库信息

读写权限：

* `checks`: 在拉取请求上创建状态检查
* `code`: 当你向文档分支提交时读取文件更改
* `deployments`: 为拉取请求生成预览部署
* `pull requests`: 通过网页编辑器创建分支和拉取请求
* `workflows`: 管理用于文档部署的 GitHub Actions

<Info>
  该应用仅会访问你明确授予其访问权限的存储库。若你启用了分支保护规则，该应用无法直接推送到受保护的分支。
</Info>

<div id="managing-repository-access">
  ## 管理存储库访问
</div>

安装我们的 GitHub 应用时，你可以授予对所有存储库或仅特定存储库的访问权限。我们建议只为存放文档的存储库授予权限。你可以随时在 [GitHub 应用设置](https://github.com/apps/mintlify/installations/new) 中修改该选择。

<div id="configuring-docs-source">
  ## 配置文档源
</div>

在控制台的 [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings) 部分更改用于构建文档的组织、存储库或 branch。

<div id="troubleshooting">
  ## 故障排除
</div>

<div id="github-app-connection-issues">
  ### GitHub 应用连接问题
</div>

如果你遇到 GitHub 应用相关问题，重置连接通常能解决大部分情况。

<Steps>
  <Step title="通过 GitHub 卸载 Mintlify 应用。">
    1. 在 GitHub 中前往 [installations](https://github.com/settings/installations)，在 Mintlify 应用旁点击 **Configure**。向下滚动并选择 **Uninstall**。
    2. 前往 [Authorized GitHub Apps](https://github.com/settings/apps/authorizations)，在 Mintlify 应用旁选择 **Revoke**。
  </Step>

  <Step title="重新安装 Mintlify 应用。">
    1. 在你的 Mintlify 控制台，前往 [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings) 并安装 GitHub 应用。
    2. 在控制台的 [My Profile](https://dashboard.mintlify.com/settings/account) 中授权你的账号。
  </Step>
</Steps>

<div id="feedback-add-ons-are-unavailable">
  ### 反馈附加组件不可用
</div>

如果你无法在控制台中启用“编辑建议”或“提交问题”选项，且你的存储库为公开，请重新验证你的 Git 设置。

<Steps>
  <Step title="Navigate to Git Settings">
    在控制台前往 [Git Settings](https://dashboard.mintlify.com/settings/deployment/git-settings)。
  </Step>

  <Step title="Revalidate your settings">
    点击 Git 设置卡片右上角的绿色勾号以重新验证你的存储库设置。这将强制更新设置，以准确反映你的存储库是公开还是私有。

    <Frame>
      <img src="https://mintcdn.com/omer-914cc1c6/1pfjDJXEL6HIHDKE/images/github/revalidate-settings-light.png?fit=max&auto=format&n=1pfjDJXEL6HIHDKE&q=85&s=c07c2b05c162d715732b5f5f81b64ada" alt="Mintlify 控制台中的 Git Settings 页面。一个橙色箭头指向用于重新验证存储库设置的绿色勾号。" className="block dark:hidden" width="1996" height="1168" data-path="images/github/revalidate-settings-light.png" />

      <img src="https://mintcdn.com/omer-914cc1c6/1pfjDJXEL6HIHDKE/images/github/revalidate-settings-dark.png?fit=max&auto=format&n=1pfjDJXEL6HIHDKE&q=85&s=d30218ba177bd1967e0f9c56698df761" alt="Mintlify 控制台中的 Git Settings 页面。一个橙色箭头指向用于重新验证存储库设置的绿色勾号。" className="hidden dark:block" width="1998" height="1170" data-path="images/github/revalidate-settings-dark.png" />
    </Frame>
  </Step>
</Steps>