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 應用程式：

• 重新導向 URI：${OVERLEAF_SITE_URL}/user/gitlab-sync/oauth2/callback
• 機密：勾選
• 範圍：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 一併核發的重新整理權杖（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。

• 請在 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 的暫存分支，並透過合併請求（merge request）進行合併，因為 GitLab 沒有提供不透過合併請求就能合併分支的 API。合併完成後，Overleaf 會刪除該暫存分支與合併請求。在 GitLab 中，只有管理員與專案擁有者可以刪除合併請求，因此對其他使用者而言，已合併的合併請求會保留在專案中。
• 合併規則：Overleaf 絕不會略過專案的合併規則。當合併請求發生衝突，或需要核准或通過管線（pipeline）時，該合併請求會保持開啟，Overleaf 會請使用者在 GitLab 中完成合併後再繼續同步。
• 管線：來自 Overleaf 的提交會像其他提交一樣觸發管線。如果您的專案會針對合併請求執行管線並要求其通過，則來自 Overleaf 的合併會如上所述等待管線完成。

​

Q&A

我可以強制推送至預設分支嗎？

回答：請保持停用對預設分支的強制推送。這也是 GitLab 的預設設定：新專案的預設分支會受到保護，任何人都無法對其強制推送。Overleaf 雖然能接手被改寫的分支，但 GitLab 同步是針對歷史紀錄只會持續增加的預設分支所設計的。

我可以重新命名已連結專案的預設分支嗎？

回答：不行。Overleaf 會持續與專案連結時的分支同步，因此一旦該分支被重新命名或移除，同步就會失敗。若要與其他分支同步，請先解除專案連結，再將儲存庫匯入為新專案，新專案會使用目前的預設分支。