> ## 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 同步

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

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

### 设置 GitLab 同步

<Warning>
  在使用 GitLab 同步之前，你需要先启用 [git-bridge](/zh-CN/on-premises/configuration/overleaf-toolkit/git-integration)。

  ```dotenv title="config/overleaf.rc" theme={null}
  GIT_BRIDGE_ENABLED=true
  ```
</Warning>

在你的 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` 已正确设置。
</Warning>

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` 或群组路径。
</Warning>

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

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

如果你所在的地区网络访问受限，可能需要配置代理才能访问 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 title="我可以强制推送到默认分支吗？">
  <strong>回答：</strong>请保持默认分支禁用强制推送。这是 GitLab 的默认设置：新项目的默认分支受保护，任何人都无法强制推送。Overleaf 可以接管被重写的分支，但 GitLab 同步是为历史记录只会增长的默认分支而设计的。
</Accordion>

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


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