GitHub 同步

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

​

设置 GitHub 同步

在使用 GitHub 同步之前，你需要先启用 git-bridge。

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

访问 developers settings 创建你的 GitHub OAuth 应用，并复制 CLIENT_ID 和 SECRET。

注意：你的 OAuth 回调 URL 为：${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback。

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

config/variables.env

# 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

在配置 GitHub OAuth 回调 URL 之前，请确保 OVERLEAF_SITE_URL 已正确设置。

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

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

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

​

GitHub Enterprise

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

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

config/variables.env

# 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 推导得出

• 请在你的企业实例上创建 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 实例。

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

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

​

谁可以关联和同步

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

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

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

​

Q&A

我可以强制推送到默认分支吗？

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

我可以重命名已关联项目的默认分支吗？

回答：请不要这样做。Overleaf 会持续与项目关联时所使用的分支同步。如需与其他分支同步，请取消项目关联，然后将仓库导入为新项目，新项目将使用当前的默认分支。