GitHub 同步

此功能由 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 回呼 URL 為：${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback。

接著，將以下設定加入您的 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

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

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

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

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