> ## 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-TW/on-premises/configuration/overleaf-toolkit/github-synchronisation) 相同：使用者連結自己的 GitLab 帳號，將專案匯出為新的 GitLab 專案、匯入 GitLab 儲存庫，並進行雙向同步。它支援 GitLab.com，以及 15.10 或更新版本的自行管理 GitLab（社群版與企業版）。

### 設定 GitLab 同步

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

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

在您的 GitLab 執行個體上，於「*使用者設定 → 應用程式*」（若要建立全站適用的應用程式，則於「*管理區域 → 應用程式*」）建立 OAuth 應用程式：

* **重新導向 URI**：`${OVERLEAF_SITE_URL}/user/gitlab-sync/oauth2/callback`
* **機密**：勾選
* **範圍**：`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 一併核發的重新整理權杖（refresh token）來更新存取權杖，因此使用者會保持連結狀態，直到他們解除連結或在 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` 的暫存分支，並透過合併請求（merge request）進行合併，因為 GitLab 沒有提供不透過合併請求就能合併分支的 API。合併完成後，Overleaf 會刪除該暫存分支與合併請求。在 GitLab 中，只有管理員與專案擁有者可以刪除合併請求，因此對其他使用者而言，已合併的合併請求會保留在專案中。
* **合併規則**：Overleaf 絕不會略過專案的合併規則。當合併請求發生衝突，或需要核准或通過管線（pipeline）時，該合併請求會保持開啟，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.