GitLab 同步

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

GitLab 同步的工作方式与 GitHub 同步 相同：用户关联自己的 GitLab 账户，将项目导出为新的 GitLab 项目，导入 GitLab 仓库，并进行双向同步。它支持 GitLab.com 以及 15.10 或更高版本的自托管 GitLab（社区版和企业版）。

​

设置 GitLab 同步

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

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

在你的 GitLab 实例上创建一个 OAuth 应用，位置为 User settings → Applications（如需创建实例级应用，则为 Admin area → Applications）：

• Redirect URI：${OVERLEAF_SITE_URL}/user/gitlab-sync/oauth2/callback
• Confidential：勾选
• Scopes：api

复制 Application ID 和 Secret，然后将以下设置添加到你的 Overleaf 环境变量文件中。

config/variables.env

# used to encrypt the user's GitLab access and refresh tokens.
# How to generate: `openssl rand -hex 32`
GITLAB_TOKEN_CIPHER_PASSWORD=0123456789ABCDEFG # changed to yours

# GitLab Sync Settings
GITLAB_SYNC_ENABLED=true
GITLAB_SYNC_CLIENT_ID=
GITLAB_SYNC_CLIENT_SECRET=

# Web address of your GitLab, defaults to https://gitlab.com
# GITLAB_SYNC_URL=https://gitlab.example.com

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

在配置 GitLab OAuth 重定向 URI 之前，请确保 OVERLEAF_SITE_URL 已正确设置。

GitLab 访问令牌会在两小时后过期。Overleaf 会使用 GitLab 随之签发的刷新令牌来刷新它们，因此用户会一直保持关联状态，直到他们取消关联或在 GitLab 中撤销该应用。

​

自托管 GitLab

将 GITLAB_SYNC_URL 设置为你的实例的网页地址，即你在浏览器中打开项目时使用的地址。REST API 地址由它推导得出：

变量	默认值
GITLAB_SYNC_URL	https://gitlab.com
GITLAB_SYNC_API_URL	${GITLAB_SYNC_URL}/api/v4

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

• 请在 GITLAB_SYNC_URL 所设置的实例上创建 OAuth 应用，在 gitlab.com 上创建的应用无法用于自托管实例。
• GITLAB_SYNC_URL 只能是网页地址。不要添加 /api/v4 或群组路径。

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

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

如果你所在的地区网络访问受限，可能需要配置代理才能访问 GitLab。请设置以下环境变量：GITLAB_SYNC_PROXY_URL=http://10.0.0.1:10808。它必须是标准的 HTTP/HTTPS 正向代理，并且不能使用 127.0.0.1。

​

谁可以关联和同步

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

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

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

​

与 GitLab 同步的工作原理

• 权限：用户需要拥有向已关联项目的默认分支推送的权限。当默认分支受保护且用户无权推送时，Overleaf 会提示他们联系项目所有者，与处理已失去访问权限的仓库时相同。
• 合并：当项目在 Overleaf 和 GitLab 中都发生了更改时，Overleaf 会将其更改提交到一个名为 overleaf-YYYY-MM-DD-HHMMSS 的临时分支，并通过合并请求进行合并，因为 GitLab 没有提供无需合并请求即可合并分支的 API。合并完成后，Overleaf 会删除该临时分支和合并请求。在 GitLab 中只有管理员和项目所有者可以删除合并请求，因此对于其他用户，已合并的合并请求会保留在项目中。
• 合并规则：Overleaf 从不绕过项目的合并规则。当合并请求存在冲突，或需要审批或通过流水线时，它会保持打开状态，Overleaf 会提示用户在 GitLab 中完成合并，然后继续同步。
• 流水线：来自 Overleaf 的提交会像其他任何提交一样触发流水线。如果你的项目为合并请求运行流水线并要求其通过，那么来自 Overleaf 的合并会等待流水线完成，如上所述。

​

Q&A

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

回答：请保持默认分支禁用强制推送。这是 GitLab 的默认设置：新项目的默认分支受保护，任何人都无法强制推送。Overleaf 可以接管被重写的分支，但 GitLab 同步是为历史记录只会增长的默认分支而设计的。

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

回答：不可以。Overleaf 会持续与项目关联时所使用的分支同步，因此一旦该分支被重命名或删除，同步就会失败。如需与其他分支同步，请取消项目关联，然后将仓库导入为新项目，新项目将使用当前的默认分支。