> ## 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-TW/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-TW/on-premises/configuration/overleaf-toolkit/integrations/git-integration.md)。
>
> ```dotenv title="config/overleaf.rc" theme={null}
> GIT_BRIDGE_ENABLED=true
> ```

在您的 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` 已正確設定。

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` 或群組路徑。

> [!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` 的暫存分支，並透過合併請求（merge request）進行合併，因為 GitLab 沒有提供不透過合併請求就能合併分支的 API。合併完成後，Overleaf 會刪除該暫存分支與合併請求。在 GitLab 中，只有管理員與專案擁有者可以刪除合併請求，因此對其他使用者而言，已合併的合併請求會保留在專案中。
* **合併規則**：Overleaf 絕不會略過專案的合併規則。當合併請求發生衝突，或需要核准或通過管線（pipeline）時，該合併請求會保持開啟，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.