> ## 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.

# GitHub 同步

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

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

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-36.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=fd5305cbb4ea8505b5eab6f41f90a57c)

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-39.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=1d8103102915872ba94119bb00fa58e0)

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-35.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=18c0d0917b5c3768593a608a53b6c19c)

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-40.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=7ebf71a5528a1b22e1e2c7f17a71b49a)

### 設定 GitHub 同步

> [!WARNING]
>
> 使用 GitHub 同步之前，您需要先啟用 [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
> ```

前往[開發者設定](https://github.com/settings/developers)建立您的 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 環境變數檔案。

```dotenv title="config/variables.env" wrap theme={null}
# 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
```

> [!WARNING]
>
> 在設定 GitHub OAuth 回呼 URL 之前，請確認 `OVERLEAF_SITE_URL` 已正確設定。

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

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

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

### GitHub Enterprise

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

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

```dotenv title="config/variables.env" wrap theme={null}
# 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` 推導 |

> [!WARNING]
>
> * 請在您的企業執行個體上建立 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 執行個體。

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

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

### 誰可以連結與同步

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

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

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

### Q\&A

> [accordion] 如何將專案連結至 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**。

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

> [accordion] 我可以重新命名已連結專案的預設分支嗎？
>
> \*\*回答：\*\*請不要這麼做。Overleaf 會持續與專案連結時的分支同步。若要與其他分支同步，請先解除專案連結，再將儲存庫匯入為新專案，新專案會使用目前的預設分支。

> [accordion] GitHub 同步顯示「Something wrong with GitHub request」
>
> \*\*回答：\*\*此訊息表示伺服器無法連線至 GitHub，例如因為網路、DNS、TLS 或代理問題。請執行 `bin/logs web` 查看完整錯誤。若伺服器需要透過代理連線至 GitHub，請設定 `GITHUB_SYNC_PROXY_URL`。

> [accordion] 我應該在 GitHub OAuth App 中停用「Expire user access tokens」嗎？
>
> \*\*回答：\*\*是的。GitHub 同步不會更新已過期的權杖。若啟用了會過期的權杖，使用者每次在權杖過期時都必須重新連接 GitHub。

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

> [accordion] 連結 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` 重新建立容器。

> [accordion] 匯入儲存庫時失敗，並顯示「EmptyZipFileError: empty\_zip\_file」或「unzip failed」
>
> \*\*回答：\*\*Overleaf 會匯入儲存庫預設分支上最新提交的 zip 封存檔，此錯誤表示該封存檔中沒有任何 Overleaf 可以匯入的檔案。請檢查 GitHub 上的預設分支：
>
> * 分支中包含專案檔案，而不只有 Overleaf 匯入時會略過的檔案：例如 `.gitignore` 與 `.gitmodules` 等點檔案（`.latexmkrc` 會保留），以及 `*.aux`、`*.log`、`*.bbl`、`*.synctex.gz`、`*.doc` 與 `*.docx` 等建置檔案。
> * 檔案並非全部位於 Git 子模組中。GitHub 的封存檔會將子模組保留為空資料夾。
> * 您預期的檔案位於預設分支，而非其他分支。匯入一律使用預設分支。

> [accordion] 匯入儲存庫時失敗，並顯示連線至「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 整合](https://ayakaleaf-pro.mintlify.site/zh-TW/on-premises/configuration/overleaf-toolkit/integrations/git-integration.md)），然後重新建立容器。Toolkit 已經設定此值；請確認 `docker-compose.override.yml` 沒有覆寫它。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.