> ## 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.

# GitLab 同步

> 让用户将项目与 GitLab.com 或自托管 GitLab 上的仓库同步。

> [!NOTE]
>
> 此功能由 [ayaka-notes/ayakaleaf-pro](https://github.com/ayaka-notes/ayakaleaf-pro) 开发。它在 v6.3.1 中作为早期预览版引入，并将在 v6.4.0 中正式发布，因此其配置和行为仍可能发生变化。如果你遇到任何问题，我们需要你的反馈。

GitLab 同步的工作方式与 [GitHub 同步](https://ayakaleaf-pro.mintlify.site/zh-CN/on-premises/configuration/overleaf-toolkit/integrations/github-synchronisation.md) 相同：用户关联自己的 GitLab 账户，将项目导出为新的 GitLab 项目，导入 GitLab 仓库，并进行双向同步。它支持 GitLab.com 以及 15.10 或更高版本的自托管 GitLab（社区版和企业版）。

### 设置 GitLab 同步

> [!WARNING]
>
> 在使用 GitLab 同步之前，你需要先启用 [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
> ```

在你的 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 环境变量文件中。

```dotenv title="config/variables.env" wrap theme={null}
# 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
```

> [!WARNING]
>
> 在配置 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`。

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

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

> [!CAUTION]
>
> 已关联的账户和项目属于其关联时所使用的实例。在将 `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

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

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

> [accordion] GitLab 同步是否支持 Git LFS？
>
> \*\*回答：\*\*不支持。Overleaf 项目不支持 Git 大文件存储（Git LFS）。由 Git LFS 跟踪的文件在 Overleaf 中显示为 LFS 指针文件，而不是其实际内容。在 GitLab 17.9 之前，导入仓库时会带入这些文件的实际内容，但首次同步会将其替换为指针文件。请改为将图片和 PDF 直接提交到仓库中。

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


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