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

# GitHub 同步

> 让用户将项目与 GitHub 或 GitHub Enterprise 仓库同步。

> [!NOTE]
>
> 此功能由 [ayaka-notes/ayakaleaf-pro](https://github.com/ayaka-notes/ayakaleaf-pro) 开发，并由 [yu-i-i/overleaf-cep](https://github.com/yu-i-i/overleaf-cep) 修改。它自 v6.2.0 起引入，目前仍处于 beta 阶段。如果你遇到任何问题，我们需要你的反馈。

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-36.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=fd5305cbb4ea8505b5eab6f41f90a57c)

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-39.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=1d8103102915872ba94119bb00fa58e0)

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-35.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=18c0d0917b5c3768593a608a53b6c19c)

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-40.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=7ebf71a5528a1b22e1e2c7f17a71b49a)

### 设置 GitHub 同步

> [!WARNING]
>
> 在使用 GitHub 同步之前，你需要先启用 [git-bridge](https://ayakaleaf-pro.mintlify.site/zh-CN/on-premises/configuration/overleaf-toolkit/integrations/git-integration.md)。
>
> ```dotenv title="config/overleaf.rc" theme={null}
> GIT_BRIDGE_ENABLED=true
> ```

访问 [developers settings](https://github.com/settings/developers) 创建你的 GitHub OAuth 应用，并复制 `CLIENT_ID` 和 `SECRET`。

**注意**：创建 OAuth App 时，请在 **Authorization callback URL** 中填写 `${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback`。Ayakaleaf Pro 会根据 `OVERLEAF_SITE_URL` 构建相同的地址，因此无需在 `config/variables.env` 中为其进行任何设置。

然后，将以下设置添加到你的 Overleaf 环境变量文件中。

```dotenv title="config/variables.env" wrap theme={null}
# used to encrypt the user's GitHub access token.
# How to generate: `openssl rand -hex 32`
GITHUB_TOKEN_CIPHER_PASSWORD=0123456789ABCDEFG # changed to yours

# Github Sync Settings
GITHUB_SYNC_ENABLED=true
GITHUB_SYNC_CLIENT_ID=
GITHUB_SYNC_CLIENT_SECRET=

# OAuth callback is: ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback
# (Optional) GITHUB_SYNC_PROXY_URL=http://10.0.0.1:10808
```

> [!WARNING]
>
> 在配置 GitHub OAuth 回调 URL 之前，请确保 `OVERLEAF_SITE_URL` 已正确设置。

如果你所在的地区网络访问受限，可能需要配置代理才能访问 GitHub。请设置以下环境变量：`GITHUB_SYNC_PROXY_URL=http://10.0.0.1:10808`。请确保你使用代理的行为符合当地法律法规。

> [!WARNING]
>
> `GITHUB_SYNC_PROXY_URL` 必须是标准的 HTTP/HTTPS 正向代理（例如 Clash 的 HTTP 端口）。不支持 `gh-proxy.org` 等 GitHub 下载镜像。

> [!WARNING]
>
> 不要使用 `127.0.0.1` 作为代理主机。如果代理运行在宿主服务器上，请使用服务器的局域网 IP 地址（例如 `192.168.1.xx`），并确保代理已配置为接受来自本地网络设备的连接。

### GitHub Enterprise

> [!NOTE]
>
> GitHub Enterprise 支持自 v6.3.1 起引入。更早的版本只能连接到 `github.com`，下列变量不起作用。

默认情况下，GitHub 同步会连接到 `github.com`。如需使用 GitHub Enterprise Server（自托管）或具有数据驻留功能的 GitHub Enterprise Cloud（`GHE.com`），请将 `GITHUB_SYNC_URL` 设置为你的实例的网页地址，即你在浏览器中打开仓库时使用的地址。

```dotenv title="config/variables.env" wrap theme={null}
# GitHub Enterprise Server
GITHUB_SYNC_URL=https://github.example.com

# or GitHub Enterprise Cloud with data residency
# GITHUB_SYNC_URL=https://octocorp.ghe.com
```

REST 和 GraphQL API 端点会按照与 GitHub CLI 相同的方式从 `GITHUB_SYNC_URL` 推导得出：

| `GITHUB_SYNC_URL` | REST API | GraphQL API |
| - | - | - |
| `https://github.com`（默认） | `https://api.github.com` | `https://api.github.com/graphql` |
| `https://SUBDOMAIN.ghe.com` | `https://api.SUBDOMAIN.ghe.com` | `https://api.SUBDOMAIN.ghe.com/graphql` |
| `https://HOST`（其他任何地址） | `https://HOST/api/v3` | `https://HOST/api/graphql` |

仅当你的实例在其他位置提供 API 端点（例如位于 API 网关之后）时，才需要设置这些端点：

| 变量 | 默认值 |
| - | - |
| `GITHUB_SYNC_URL` | `https://github.com` |
| `GITHUB_SYNC_API_URL` | 由 `GITHUB_SYNC_URL` 推导得出，参见上表 |
| `GITHUB_SYNC_GRAPHQL_URL` | 如果设置了 `GITHUB_SYNC_API_URL`，则由其推导得出（`/api/v3` 变为 `/api/graphql`，否则追加 `/graphql`），否则由 `GITHUB_SYNC_URL` 推导得出 |

> [!WARNING]
>
> * 请在你的企业实例上创建 OAuth 应用（*Settings → Developer settings → OAuth Apps*），在 `github.com` 上创建的应用无法在那里使用。回调 URL 相同：`${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback`。
> * `GITHUB_SYNC_URL` 只能是网页地址。不要将其设置为 API 地址（例如 `https://api.github.com` 或 `https://HOST/api/v3`），也不要添加组织路径。
> * 这三个地址必须指向同一个 GitHub 实例。

> [!NOTE]
>
> 如果你的实例使用由私有 CA 签发的证书，请将 CA 证书挂载到容器中，并将 `NODE_EXTRA_CA_CERTS` 指向它，例如 `NODE_EXTRA_CA_CERTS=/var/lib/overleaf/certs/github-ca.pem`。

> [!CAUTION]
>
> 已关联的账户和项目属于其关联时所使用的实例。在将 `GITHUB_SYNC_URL` 切换到另一个实例之前，请让用户取消关联他们的 GitHub 账户和项目。

### 谁可以关联和同步

与 Overleaf Cloud 一样，只有项目所有者才能将项目关联到 GitHub 仓库。关联完成后，每位拥有编辑权限的协作者都可以同步该项目。

| 操作 | 谁可以执行 |
| - | - |
| 将项目导出到新的 GitHub 仓库 | 项目所有者 |
| 将 GitHub 仓库导入为新项目 | 任何用户，该用户将成为新项目的所有者 |
| 对已关联项目执行拉取、推送和合并 | 所有者和拥有编辑权限的协作者 |
| 取消项目与其仓库的关联 | 项目所有者 |

* Overleaf 使用执行同步的用户的 GitHub 账户与 GitHub 通信，因此每位执行同步的协作者都需要关联自己的 GitHub 账户，并且需要拥有向仓库默认分支推送的权限。
* 仅有查看权限的协作者无法对该项目使用 GitHub 同步。

### Q\&A

> [accordion] 如何将项目关联到 GitHub 并进行同步？
>
> \*\*回答：\*\*在编辑器中，打开 **Integrations** 并点击 **GitHub**。如果你的 GitHub 账户尚未关联，请先点击 **Link to your GitHub account**。在 **Export Project to GitHub** 中，输入仓库名称，在 **Repository visibility** 下选择 **Private**，然后点击 **Create a GitHub repository**。
>
> 之后，同一卡片会打开 **Sync with GitHub**，其中列出 GitHub 中的新提交。点击 **Sync** 即可将你在 Overleaf 中的更改提交到默认分支，并将 GitHub 中的更改合并到项目中。同步是双向的，但只有在有人点击 **Sync** 时才会运行；没有定时同步。当两边都有更改时，Overleaf 会通过一个名为 `overleaf-YYYY-MM-DD-HHMMSS` 的临时分支进行合并。如果该合并出现冲突，请在 GitHub 中自行合并该分支，然后点击 **I have manually merged. Continue**。

> [accordion] 我可以强制推送到默认分支吗？
>
> \*\*回答：\*\*我们不建议这样做。Overleaf 会检测到强制推送并发出警告，然后接管被重写的分支，合并自上次同步以来在 Overleaf 中所做的更改。为避免意外情况，请在仓库设置中保护默认分支，禁止强制推送。

> [accordion] 我可以重命名已关联项目的默认分支吗？
>
> \*\*回答：\*\*请不要这样做。Overleaf 会持续与项目关联时所使用的分支同步。如需与其他分支同步，请取消项目关联，然后将仓库导入为新项目，新项目将使用当前的默认分支。

> [accordion] GitHub 同步显示“Something wrong with GitHub request”
>
> \*\*回答：\*\*此消息表示服务器无法访问 GitHub，例如由于网络、DNS、TLS 或代理问题。运行 `bin/logs web` 查看完整错误。如果服务器需要通过代理访问 GitHub，请设置 `GITHUB_SYNC_PROXY_URL`。

> [accordion] 是否应在 GitHub OAuth App 中禁用“Expire user access tokens”？
>
> \*\*回答：\*\*是的。GitHub 同步不会续期已过期的令牌。如果启用了令牌过期，用户每次令牌过期时都必须重新连接 GitHub。

> [accordion] 我的实例需要能从互联网访问吗？
>
> \*\*回答：\*\*不需要。关联账户是通过用户的浏览器进行的，因此 OAuth 回调地址只需要能在用户的浏览器中打开即可。服务器只需要能访问 GitHub；如果为此需要代理，请设置 `GITHUB_SYNC_PROXY_URL`。GitHub 从不调用你的实例：只有当用户在编辑器中同步项目时，项目才会被同步。

> [accordion] 关联 GitHub 账户失败，或者跳转回来后未完成关联
>
> \*\*回答：\*\*请按顺序检查以下几点：
>
> * 通过 `OVERLEAF_SITE_URL` 中设置的确切地址打开 Overleaf。GitHub 会将你重定向回 `${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback`，而你的登录状态只存在于你开始操作时所用的地址上，因此使用其他主机、IP 或端口会停留在登录页面，或显示“Restricted, sorry you don’t have permission to load this page”。
> * OAuth App 的 **Authorization callback URL** 必须是 `${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback`，且协议、主机和端口都相同。
> * 如果错误页面显示 `Failed to obtain access token from Git server`，说明 GitHub 没有返回令牌：请检查 `GITHUB_SYNC_CLIENT_ID` 和 `GITHUB_SYNC_CLIENT_SECRET`，并确认服务器能够访问 GitHub。运行 `bin/logs web` 查看完整错误。
>
> 修改 `config/variables.env` 后，运行 `bin/up` 重新创建容器。

> [accordion] 导入仓库失败，提示“EmptyZipFileError: empty\_zip\_file”或“unzip failed”
>
> \*\*回答：\*\*Overleaf 会导入仓库默认分支上最新提交的 zip 归档，此错误表示该归档中没有 Overleaf 可以导入的文件。请检查 GitHub 上的默认分支：
>
> * 它包含项目文件，而不只是 Overleaf 在导入时会跳过的文件：例如 `.gitignore` 和 `.gitmodules` 等点文件（`.latexmkrc` 会被保留），以及 `*.aux`、`*.log`、`*.bbl`、`*.synctex.gz`、`*.doc` 和 `*.docx` 等构建文件。
> * 文件并非只存在于 Git 子模块中。GitHub 的归档会将子模块保留为空文件夹。
> * 你期望的文件位于默认分支上，而不是其他分支。导入始终使用默认分支。

> [accordion] 导入仓库失败，提示连接“sharelatex:3054”时出现“connect ECONNREFUSED”
>
> **回答：**`V1_HISTORY_URL` 被设置为 `http://sharelatex:3054`，这是本文档旧版本给出的值。端口 `3054` 是 `project-history` 服务，它只在容器内部监听，而 `V1_HISTORY_URL` 必须指向 `history-v1`。Overleaf 会将导入仓库中的每个二进制文件（图片、PDF）保存到 `history-v1`，因此导入会失败；在编辑器中上传此类文件也会以同样的方式失败。在你的 `docker-compose.yml` 中，为 `sharelatex` 服务设置 `V1_HISTORY_URL: "http://sharelatex:3100/api"`（参见 [Git 集成](https://ayakaleaf-pro.mintlify.site/zh-CN/on-premises/configuration/overleaf-toolkit/integrations/git-integration.md)），然后重新创建容器。Toolkit 已经设置了该值；请检查 `docker-compose.override.yml` 没有覆盖它。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.