Gitea 同步

此功能由 ayaka-notes/ayakaleaf-pro 開發，於 v6.3.2 以早期預覽版推出，並將在 v6.4.0 正式發布，因此其設定與行為仍可能變更。如果您遇到任何問題，歡迎提供回饋。

Gitea 同步的運作方式與 GitHub 同步 及 GitLab 同步 相同：使用者連結自己的 Gitea 帳號，將專案匯出為新的 Gitea 儲存庫、匯入 Gitea 儲存庫，並進行雙向同步。它支援 1.23 或更新版本的 Gitea，無論是在 gitea.com 或您自己的執行個體上。

​

設定 Gitea 同步

使用 Gitea 同步之前，您需要先啟用 git-bridge。

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

在您的 Gitea 執行個體上，於「設定 → 應用程式 → 管理 OAuth2 應用程式」（若要建立全站適用的應用程式，則於「網站管理 → 整合 → 應用程式」）建立 OAuth2 應用程式：

• 應用程式名稱：例如 Overleaf，使用者在授權時會看到此名稱
• 重新導向 URI：${OVERLEAF_SITE_URL}/user/gitea-sync/oauth2/callback
• 機密用戶端：勾選

複製 Client ID 與 Client Secret，接著將以下設定加入您的 Overleaf 環境變數檔案。

config/variables.env

# used to encrypt the user's Gitea access and refresh tokens.
# How to generate: `openssl rand -hex 32`
GITEA_TOKEN_CIPHER_PASSWORD=0123456789ABCDEFG # changed to yours

# Gitea Sync Settings
GITEA_SYNC_ENABLED=true
GITEA_SYNC_CLIENT_ID=
GITEA_SYNC_CLIENT_SECRET=

# Web address of your Gitea (its ROOT_URL), defaults to https://gitea.com
# GITEA_SYNC_URL=https://gitea.example.com

# OAuth callback is: ${OVERLEAF_SITE_URL}/user/gitea-sync/oauth2/callback
# (Optional) GITEA_SYNC_PROXY_URL=http://10.0.0.1:10808

在設定 Gitea 重新導向 URI 之前，請確認 OVERLEAF_SITE_URL 已正確設定。

Overleaf 會在使用者連結帳號時，一次要求同步所需的所有權限，因此使用者永遠不必因為缺少權限而重新連結：

範圍	用途
write:repository	儲存庫、其檔案（包括 .gitea/workflows 下的 CI 工作流程）、分支與拉取請求
write:user	匯出時建立使用者的儲存庫（Gitea 在 POST /user/repos 時會要求此範圍）
write:organization	列出使用者的組織，並在匯出時於組織下建立儲存庫

Gitea 會在使用者授權應用程式時顯示這些範圍，並將權杖限制在這些範圍內。

Gitea 存取權杖會在一小時後過期（[oauth2] ACCESS_TOKEN_EXPIRATION_TIME）。Overleaf 會使用 Gitea 一併核發的重新整理權杖（refresh token）來更新存取權杖，即使 Gitea 會在使用後作廢重新整理權杖（INVALIDATE_REFRESH_TOKENS = true）也能正常運作，因此使用者會保持連結狀態，直到他們解除連結或在 Gitea 中撤銷該應用程式為止。

​

您的 Gitea 執行個體

將 GITEA_SYNC_URL 設為您執行個體的網頁位址，也就是它的 ROOT_URL，即您在瀏覽器中開啟儲存庫時使用的位址。REST API 位址會由此推導而來：

變數	預設值
GITEA_SYNC_URL	https://gitea.com
GITEA_SYNC_API_URL	${GITEA_SYNC_URL}/api/v1

架設於子路徑下的 Gitea 同樣可行，例如 GITEA_SYNC_URL=https://example.com/gitea。只有當您的執行個體在其他位置提供 API 時（例如位於 API 閘道之後），才需要設定 GITEA_SYNC_API_URL。

• 請在 GITEA_SYNC_URL 所設定的執行個體上建立 OAuth2 應用程式；在其他執行個體上建立的應用程式無法使用。
• GITEA_SYNC_URL 只能是網頁位址。請勿加上 /api/v1 或使用者、組織路徑。
• Overleaf 透過 Gitea 的檔案 API 進行提交，而這需要網頁編輯器：請保持 [repository.editor] 為啟用狀態（預設值）。

如果您的執行個體使用由私人 CA 簽發的憑證，請將該 CA 憑證掛載到容器中，並將 NODE_EXTRA_CA_CERTS 指向它，例如 NODE_EXTRA_CA_CERTS=/var/lib/overleaf/certs/gitea-ca.pem。

已連結的帳號與專案隸屬於當初連結時所使用的執行個體。在將 GITEA_SYNC_URL 切換至其他執行個體之前，請先要求使用者解除其 Gitea 帳號與專案的連結。

如果您位於網路存取受限的地區，可能需要設定代理伺服器才能存取 Gitea。請設定以下環境變數：GITEA_SYNC_PROXY_URL=http://10.0.0.1:10808。它必須是標準的 HTTP/HTTPS 正向代理伺服器，且不得使用 127.0.0.1。

​

誰可以連結與同步

與 Overleaf Cloud 相同，只有專案擁有者可以將專案連結至 Gitea 儲存庫。連結完成後，每位具有編輯權限的協作者都可以進行同步。

操作	可執行者
將專案匯出至新的 Gitea 儲存庫	專案擁有者
將 Gitea 儲存庫匯入為新專案	任何使用者，並成為新專案的擁有者
對已連結的專案執行拉取、推送與合併	擁有者及具有編輯權限的協作者
解除專案與其儲存庫的連結	專案擁有者

• Overleaf 會使用執行同步之使用者的 Gitea 帳號與 Gitea 溝通，因此每位執行同步的協作者都需要連結自己的 Gitea 帳號，且必須具有推送至該儲存庫預設分支的權限。
• 僅具檢視權限的協作者無法對該專案使用 Gitea 同步。
• 在 Overleaf 中解除帳號連結會捨棄其權杖；Gitea 沒有撤銷權杖的 API，因此如有需要，請同時在 Gitea 的「設定 → 應用程式」中撤銷授權。

​

Gitea 的同步運作方式

• 權限：使用者必須具有推送至已連結儲存庫預設分支的權限。當分支保護規則不允許使用者推送時，Overleaf 會請他們聯絡專案擁有者，處理方式與失去存取權限的儲存庫相同。
• 合併：當專案同時在 Overleaf 與 Gitea 中有所變更時，Overleaf 會將其變更提交至名為 overleaf-YYYY-MM-DD-HHMMSS 的暫存分支，並以儲存庫的預設合併方式透過拉取請求（pull request）進行合併，因為 Gitea 沒有提供不透過拉取請求就能合併分支的 API。合併完成後，Overleaf 會刪除該暫存分支；已合併的拉取請求則會作為紀錄保留在儲存庫中。
• 合併規則：Overleaf 絕不會略過儲存庫的分支保護。當拉取請求發生衝突，或需要核准或通過狀態檢查時，該拉取請求會保持開啟，Overleaf 會請使用者在 Gitea 中完成合併後再繼續同步。
• CI 工作流程：Overleaf 不會顯示 .gitea/workflows/ 等點檔案（dotfile），並會將其維持在儲存庫中的原樣。來自 Overleaf 的提交會像其他提交一樣觸發 Gitea Actions。

​

Q&A

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

回答：請保持停用對預設分支的強制推送，例如透過分支保護規則。Overleaf 雖然能接手被改寫的分支，但 Gitea 同步是針對歷史紀錄只會持續增加的預設分支所設計的。

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

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

Gitea 同步支援 Git LFS 嗎？

回答：不支援。Overleaf 專案不支援 Git 大型檔案儲存（Git LFS）。由 Git LFS 追蹤的檔案在 Overleaf 中會顯示為 LFS 指標檔案，而非其實際內容。請改為將圖片與 PDF 直接提交至儲存庫。

它支援 SHA-256 儲存庫嗎？

回答：目前尚不支援。Overleaf 是以 SHA-1 ID 比對檔案，因此在以 SHA-256 物件格式建立的儲存庫中，每次拉取都會改寫所有檔案，即使是未變更的檔案也一樣。雖然不會遺失任何資料，但請使用預設的 SHA-1 格式。

它支援 Forgejo 嗎？

回答：Gitea 同步僅針對 Gitea 開發與測試。