GitHub 同步

讓使用者將專案與 GitHub 或 GitHub Enterprise 儲存庫同步。

此功能由 ayaka-notes/ayakaleaf-pro 開發，並由 yu-i-i/overleaf-cep 修改。此功能自 v6.2.0 起推出，目前仍處於 Beta 階段。如果您遇到任何問題，歡迎提供回饋。

​

設定 GitHub 同步

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

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

前往開發者設定建立您的 GitHub OAuth 應用程式，並複製您的 CLIENT_ID 與 SECRET。

注意：建立 OAuth App 時，請在 Authorization callback URL 中輸入 ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback。Ayakaleaf Pro 會根據 OVERLEAF_SITE_URL 組出相同的位址，因此不需要在 config/variables.env 中為其進行任何設定。

接著，將以下設定加入您的 Overleaf 環境變數檔案。

config/variables.env

# used to encrypt the user's GitHub access token.
# How to generate: `openssl rand -hex 32`
GITHUB_TOKEN_CIPHER_PASSWORD=0123456789ABCDEFG # changed to yours

# Github Sync Settings
GITHUB_SYNC_ENABLED=true
GITHUB_SYNC_CLIENT_ID=
GITHUB_SYNC_CLIENT_SECRET=

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

在設定 GitHub OAuth 回呼 URL 之前，請確認 OVERLEAF_SITE_URL 已正確設定。

如果您位於網路存取受限的地區，可能需要設定代理伺服器才能存取 GitHub。請設定以下環境變數：GITHUB_SYNC_PROXY_URL=http://10.0.0.1:10808。請確保您使用代理伺服器的行為符合當地法律法規。

GITHUB_SYNC_PROXY_URL 必須是標準的 HTTP/HTTPS 正向代理伺服器（例如 Clash 的 HTTP 連接埠）。不支援 gh-proxy.org 等 GitHub 下載鏡像。

請勿將 127.0.0.1 用作代理主機。如果代理伺服器執行於主機伺服器上，請使用伺服器的區域網路 IP 位址（例如 192.168.1.xx），並確認代理伺服器已設定為接受來自區域網路裝置的連線。

​

GitHub Enterprise

GitHub Enterprise 支援自 v6.3.1 起推出。較早的版本只能連線至 github.com，下方的變數不會生效。

GitHub 同步預設會連線至 github.com。若要使用 GitHub Enterprise Server（自行託管）或具資料落地（data residency）功能的 GitHub Enterprise Cloud（GHE.com），請將 GITHUB_SYNC_URL 設為您執行個體的網頁位址，也就是您在瀏覽器中開啟儲存庫時使用的位址。

config/variables.env

# GitHub Enterprise Server
GITHUB_SYNC_URL=https://github.example.com

# or GitHub Enterprise Cloud with data residency
# GITHUB_SYNC_URL=https://octocorp.ghe.com

REST 與 GraphQL API 端點會以與 GitHub CLI 相同的方式，由 GITHUB_SYNC_URL 推導而來：

GITHUB_SYNC_URL	REST API	GraphQL API
https://github.com（預設）	https://api.github.com	https://api.github.com/graphql
https://SUBDOMAIN.ghe.com	https://api.SUBDOMAIN.ghe.com	https://api.SUBDOMAIN.ghe.com/graphql
https://HOST（其他任何位址）	https://HOST/api/v3	https://HOST/api/graphql

只有當您的執行個體在其他位置提供 API 端點時（例如位於 API 閘道之後），才需要設定這些端點：

變數	預設值
GITHUB_SYNC_URL	https://github.com
GITHUB_SYNC_API_URL	由 GITHUB_SYNC_URL 推導而來，請參閱上表
GITHUB_SYNC_GRAPHQL_URL	若已設定 GITHUB_SYNC_API_URL，則由其推導（/api/v3 會變為 /api/graphql，否則會附加 /graphql）；否則由 GITHUB_SYNC_URL 推導

• 請在您的企業執行個體上建立 OAuth 應用程式（「Settings → Developer settings → OAuth Apps」）；在 github.com 上建立的應用程式無法在該處使用。回呼 URL 相同：${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback。
• GITHUB_SYNC_URL 只能是網頁位址。請勿將其設為 https://api.github.com 或 https://HOST/api/v3 等 API 位址，也請勿加上組織路徑。
• 這三個位址都必須指向同一個 GitHub 執行個體。

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

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

​

誰可以連結與同步

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

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

• Overleaf 會使用執行同步之使用者的 GitHub 帳號與 GitHub 溝通，因此每位執行同步的協作者都需要連結自己的 GitHub 帳號，且必須具有推送至該儲存庫預設分支的權限。
• 僅具檢視權限的協作者無法對該專案使用 GitHub 同步。

​

Q&A

如何將專案連結至 GitHub 並進行同步？

回答：在編輯器中開啟 Integrations，然後點選 GitHub。若您的 GitHub 帳號尚未連結，請先點選 Link to your GitHub account。在 Export Project to GitHub 中輸入儲存庫名稱，於 Repository visibility 下選擇 Private，然後點選 Create a GitHub repository。

之後，同一張卡片會開啟 Sync with GitHub，其中會列出 GitHub 中的新提交。點選 Sync 即可將您在 Overleaf 中的變更提交至預設分支，並將 GitHub 的變更帶入專案。同步是雙向的，但只會在有人點選 Sync 時執行；沒有排程同步。當兩邊都有變更時，Overleaf 會透過名為 overleaf-YYYY-MM-DD-HHMMSS 的暫存分支進行合併。若該合併發生衝突，請自行在 GitHub 中合併該分支，然後點選 I have manually merged. Continue。

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

回答：我們不建議這麼做。Overleaf 會偵測強制推送並發出警告，接著接手被改寫的分支，並合併自上次同步以來在 Overleaf 中所做的變更。為避免意外，請在儲存庫設定中保護預設分支，防止強制推送。

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

回答：請不要這麼做。Overleaf 會持續與專案連結時的分支同步。若要與其他分支同步，請先解除專案連結，再將儲存庫匯入為新專案，新專案會使用目前的預設分支。

GitHub 同步顯示「Something wrong with GitHub request」

回答：此訊息表示伺服器無法連線至 GitHub，例如因為網路、DNS、TLS 或代理問題。請執行 bin/logs web 查看完整錯誤。若伺服器需要透過代理連線至 GitHub，請設定 GITHUB_SYNC_PROXY_URL。

我應該在 GitHub OAuth App 中停用「Expire user access tokens」嗎？

回答：是的。GitHub 同步不會更新已過期的權杖。若啟用了會過期的權杖，使用者每次在權杖過期時都必須重新連接 GitHub。

我的執行個體需要能從網際網路存取嗎？

回答：不需要。連結帳號是透過使用者的瀏覽器進行的，因此 OAuth 回呼位址只需要能在使用者的瀏覽器中開啟即可。伺服器只需要能連線至 GitHub；若需要透過代理連線，請設定 GITHUB_SYNC_PROXY_URL。GitHub 永遠不會呼叫您的執行個體：只有在使用者於編輯器中同步專案時，專案才會進行同步。

連結 GitHub 帳號失敗，或未完成連結就被導回

回答：請依序檢查以下項目：

• 請使用與 OVERLEAF_SITE_URL 中設定完全相同的位址開啟 Overleaf。GitHub 會將您導回 ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback，而您的登入狀態只存在於您一開始使用的位址上，因此若使用其他主機、IP 或連接埠，最後會停在登入頁面，或顯示「Restricted, sorry you don’t have permission to load this page」。
• OAuth App 的 Authorization callback URL 必須是 ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback，且通訊協定、主機與連接埠皆須相同。
• 若錯誤頁面顯示 Failed to obtain access token from Git server，表示 GitHub 沒有傳回權杖：請檢查 GITHUB_SYNC_CLIENT_ID 與 GITHUB_SYNC_CLIENT_SECRET，並確認伺服器能夠連線至 GitHub。執行 bin/logs web 以查看完整錯誤。

變更 config/variables.env 後，請執行 bin/up 重新建立容器。

匯入儲存庫時失敗，並顯示「EmptyZipFileError: empty_zip_file」或「unzip failed」

回答：Overleaf 會匯入儲存庫預設分支上最新提交的 zip 封存檔，此錯誤表示該封存檔中沒有任何 Overleaf 可以匯入的檔案。請檢查 GitHub 上的預設分支：

• 分支中包含專案檔案，而不只有 Overleaf 匯入時會略過的檔案：例如 .gitignore 與 .gitmodules 等點檔案（.latexmkrc 會保留），以及 *.aux、*.log、*.bbl、*.synctex.gz、*.doc 與 *.docx 等建置檔案。
• 檔案並非全部位於 Git 子模組中。GitHub 的封存檔會將子模組保留為空資料夾。
• 您預期的檔案位於預設分支，而非其他分支。匯入一律使用預設分支。

匯入儲存庫時失敗，並顯示連線至「sharelatex:3054」時發生「connect ECONNREFUSED」

回答：V1_HISTORY_URL 被設為 http://sharelatex:3054，這是本文件舊版本所提供的值。連接埠 3054 是 project-history 服務，只在容器內部監聽，而 V1_HISTORY_URL 必須指向 history-v1。Overleaf 會將匯入儲存庫中的每個二進位檔案（圖片、PDF）儲存至 history-v1，因此匯入會失敗；在編輯器中上傳此類檔案也會以同樣方式失敗。請在您的 docker-compose.yml 中，於 sharelatex 服務設定 V1_HISTORY_URL: "http://sharelatex:3100/api"（請參閱 Git 整合），然後重新建立容器。Toolkit 已經設定此值；請確認 docker-compose.override.yml 沒有覆寫它。