GitHub 同步

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

此功能由 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 App 时，请在 Authorization callback URL 中填写 ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback。Ayakaleaf Pro 会根据 OVERLEAF_SITE_URL 构建相同的地址，因此无需在 config/variables.env 中为其进行任何设置。

然后，将以下设置添加到你的 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

如何将项目关联到 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。

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

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

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

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

GitHub 同步显示“Something wrong with GitHub request”

回答：此消息表示服务器无法访问 GitHub，例如由于网络、DNS、TLS 或代理问题。运行 bin/logs web 查看完整错误。如果服务器需要通过代理访问 GitHub，请设置 GITHUB_SYNC_PROXY_URL。

是否应在 GitHub OAuth App 中禁用“Expire user access tokens”？

回答：是的。GitHub 同步不会续期已过期的令牌。如果启用了令牌过期，用户每次令牌过期时都必须重新连接 GitHub。

我的实例需要能从互联网访问吗？

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

关联 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 重新创建容器。

导入仓库失败，提示“EmptyZipFileError: empty_zip_file”或“unzip failed”

回答：Overleaf 会导入仓库默认分支上最新提交的 zip 归档，此错误表示该归档中没有 Overleaf 可以导入的文件。请检查 GitHub 上的默认分支：

• 它包含项目文件，而不只是 Overleaf 在导入时会跳过的文件：例如 .gitignore 和 .gitmodules 等点文件（.latexmkrc 会被保留），以及 *.aux、*.log、*.bbl、*.synctex.gz、*.doc 和 *.docx 等构建文件。
• 文件并非只存在于 Git 子模块中。GitHub 的归档会将子模块保留为空文件夹。
• 你期望的文件位于默认分支上，而不是其他分支。导入始终使用默认分支。

导入仓库失败，提示连接“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 集成），然后重新创建容器。Toolkit 已经设置了该值；请检查 docker-compose.override.yml 没有覆盖它。