> ## 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. # Đồng bộ hóa GitHub > Cho phép người dùng đồng bộ dự án của họ với các kho lưu trữ GitHub hoặc GitHub Enterprise. > [!NOTE] > > Tính năng này được phát triển bởi [ayaka-notes/ayakaleaf-pro](https://github.com/ayaka-notes/ayakaleaf-pro) và được chỉnh sửa bởi [yu-i-i/overleaf-cep](https://github.com/yu-i-i/overleaf-cep). Tính năng được giới thiệu từ v6.2.0 trở đi và vẫn đang ở trạng thái beta. Nếu gặp bất kỳ vấn đề nào, chúng tôi rất mong nhận được phản hồi của bạn. ![](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) ### Thiết lập đồng bộ hóa GitHub > [!WARNING] > > Bạn cần bật [git-bridge](https://ayakaleaf-pro.mintlify.site/vi/on-premises/configuration/overleaf-toolkit/integrations/git-integration.md) trước khi sử dụng đồng bộ hóa GitHub. > > ```dotenv title="config/overleaf.rc" theme={null} > GIT_BRIDGE_ENABLED=true > ``` Truy cập [developers settings](https://github.com/settings/developers) để tạo ứng dụng GitHub OAuth của bạn, sau đó sao chép `CLIENT_ID` và `SECRET`. **Lưu ý**: khi tạo OAuth App, hãy nhập `${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback` vào ô **Authorization callback URL**. Ayakaleaf Pro tạo cùng địa chỉ này từ `OVERLEAF_SITE_URL`, vì vậy bạn không cần đặt gì cho nó trong `config/variables.env`. Sau đó, thêm các cài đặt sau vào tệp biến môi trường của 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] > > Trước khi cấu hình URL callback OAuth của GitHub, hãy đảm bảo `OVERLEAF_SITE_URL` đã được đặt chính xác. Nếu bạn ở khu vực có hạn chế truy cập mạng, có thể bạn cần cấu hình proxy để truy cập GitHub. Hãy đặt biến môi trường sau: `GITHUB_SYNC_PROXY_URL=http://10.0.0.1:10808`. Vui lòng đảm bảo việc sử dụng proxy của bạn tuân thủ luật pháp và quy định địa phương. > [!WARNING] > > `GITHUB_SYNC_PROXY_URL` phải là một proxy chuyển tiếp HTTP/HTTPS tiêu chuẩn (ví dụ: cổng HTTP của Clash). Các mirror tải xuống GitHub như `gh-proxy.org` không được hỗ trợ. > [!WARNING] > > Không sử dụng `127.0.0.1` làm máy chủ proxy. Nếu proxy chạy trên máy chủ host, hãy dùng địa chỉ IP LAN của máy chủ (ví dụ `192.168.1.xx`) và đảm bảo proxy được cấu hình để chấp nhận kết nối từ các thiết bị trong mạng cục bộ. ### GitHub Enterprise > [!NOTE] > > Hỗ trợ GitHub Enterprise được giới thiệu từ v6.3.1 trở đi. Các phiên bản trước chỉ kết nối tới `github.com` và các biến bên dưới không có tác dụng. Theo mặc định, đồng bộ hóa GitHub kết nối tới `github.com`. Để sử dụng GitHub Enterprise Server (tự lưu trữ) hoặc GitHub Enterprise Cloud với lưu trữ dữ liệu theo khu vực (`GHE.com`), hãy đặt `GITHUB_SYNC_URL` thành địa chỉ web của phiên bản của bạn, tức là địa chỉ bạn dùng để mở các kho lưu trữ trong trình duyệt. ```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 ``` Các endpoint REST API và GraphQL API được suy ra từ `GITHUB_SYNC_URL` theo cùng cách mà GitHub CLI thực hiện: | `GITHUB_SYNC_URL` | REST API | GraphQL API | | - | - | - | | `https://github.com` (mặc định) | `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` (bất kỳ địa chỉ nào khác) | `https://HOST/api/v3` | `https://HOST/api/graphql` | Chỉ đặt các endpoint API khi phiên bản của bạn phục vụ chúng ở một địa chỉ khác, ví dụ phía sau một API gateway: | Biến | Mặc định | | - | - | | `GITHUB_SYNC_URL` | `https://github.com` | | `GITHUB_SYNC_API_URL` | Được suy ra từ `GITHUB_SYNC_URL`, xem bảng ở trên | | `GITHUB_SYNC_GRAPHQL_URL` | Được suy ra từ `GITHUB_SYNC_API_URL` khi biến này được đặt (`/api/v3` trở thành `/api/graphql`, nếu không thì `/graphql` được nối thêm vào cuối), ngược lại thì suy ra từ `GITHUB_SYNC_URL` | > [!WARNING] > > * Hãy tạo ứng dụng OAuth trên phiên bản enterprise của bạn (*Settings → Developer settings → OAuth Apps*), ứng dụng từ `github.com` sẽ không hoạt động ở đó. URL callback vẫn giữ nguyên: `${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback`. > * `GITHUB_SYNC_URL` chỉ là địa chỉ web. Không đặt nó thành một địa chỉ API như `https://api.github.com` hoặc `https://HOST/api/v3`, và không thêm đường dẫn tổ chức. > * Cả ba địa chỉ phải trỏ tới cùng một phiên bản GitHub. > [!NOTE] > > Nếu phiên bản của bạn sử dụng chứng chỉ từ một CA riêng, hãy mount chứng chỉ CA vào container và trỏ `NODE_EXTRA_CA_CERTS` tới chứng chỉ đó, ví dụ `NODE_EXTRA_CA_CERTS=/var/lib/overleaf/certs/github-ca.pem`. > [!CAUTION] > > Các tài khoản và dự án đã liên kết thuộc về phiên bản mà chúng được liên kết. Trước khi chuyển `GITHUB_SYNC_URL` sang một phiên bản khác, hãy yêu cầu người dùng hủy liên kết tài khoản GitHub và các dự án của họ. ### Ai có thể liên kết và đồng bộ Giống như trên Overleaf Cloud, chỉ chủ sở hữu dự án mới có thể liên kết dự án với một kho lưu trữ GitHub. Sau khi đã liên kết, mọi cộng tác viên có quyền chỉnh sửa đều có thể đồng bộ dự án. | Hành động | Ai có thể thực hiện | | - | - | | Xuất dự án sang một kho lưu trữ GitHub mới | Chủ sở hữu dự án | | Nhập một kho lưu trữ GitHub vào một dự án mới | Bất kỳ người dùng nào, người đó sẽ trở thành chủ sở hữu của dự án mới | | Pull, push và merge một dự án đã liên kết | Chủ sở hữu và các cộng tác viên có quyền chỉnh sửa | | Hủy liên kết dự án khỏi kho lưu trữ của nó | Chủ sở hữu dự án | * Overleaf giao tiếp với GitHub bằng tài khoản GitHub của người dùng thực hiện đồng bộ, vì vậy mỗi cộng tác viên thực hiện đồng bộ cần liên kết tài khoản GitHub của riêng mình và phải được phép push lên nhánh mặc định của kho lưu trữ. * Cộng tác viên chỉ có quyền xem không thể sử dụng đồng bộ hóa GitHub cho dự án. ### Q\&A > [accordion] Làm thế nào để liên kết một dự án với GitHub và đồng bộ nó? > > **Trả lời:** Trong trình soạn thảo, mở **Integrations** và nhấp vào **GitHub**. Nếu tài khoản GitHub của bạn chưa được liên kết, trước tiên hãy nhấp vào **Link to your GitHub account**. Trong **Export Project to GitHub**, nhập tên kho lưu trữ, chọn **Private** trong **Repository visibility**, rồi nhấp vào **Create a GitHub repository**. > > Sau đó, cùng thẻ này sẽ mở **Sync with GitHub**, liệt kê các commit mới trên GitHub. Nhấp vào **Sync** để commit các thay đổi Overleaf của bạn lên nhánh mặc định và đưa các thay đổi trên GitHub vào dự án. Việc đồng bộ diễn ra theo cả hai chiều nhưng chỉ chạy khi có người nhấp vào **Sync**; không có đồng bộ theo lịch. Khi cả hai phía đều có thay đổi, Overleaf hợp nhất thông qua một nhánh tạm thời có tên `overleaf-YYYY-MM-DD-HHMMSS`. Nếu việc hợp nhất đó có xung đột, hãy tự hợp nhất nhánh trên GitHub, rồi nhấp vào **I have manually merged. Continue**. > [accordion] Tôi có thể force push lên nhánh mặc định không? > > **Trả lời:** Chúng tôi không khuyến khích điều này. Overleaf sẽ phát hiện force push, đưa ra cảnh báo và tiếp quản nhánh đã bị viết lại, hợp nhất các thay đổi được thực hiện trong Overleaf kể từ lần đồng bộ gần nhất. Để tránh những bất ngờ, hãy bảo vệ nhánh mặc định khỏi force push trong phần cài đặt của kho lưu trữ. > [accordion] Tôi có thể đổi tên nhánh mặc định của một dự án đã liên kết không? > > **Trả lời:** Vui lòng không làm vậy. Overleaf tiếp tục đồng bộ với nhánh mà dự án đã được liên kết. Để đồng bộ với một nhánh khác, hãy hủy liên kết dự án, sau đó nhập kho lưu trữ vào một dự án mới, dự án này sẽ sử dụng nhánh mặc định hiện tại. > [accordion] Đồng bộ GitHub hiển thị “Something wrong with GitHub request” > > **Trả lời:** Thông báo này có nghĩa là máy chủ không thể kết nối tới GitHub, ví dụ do sự cố mạng, DNS, TLS hoặc proxy. Hãy chạy `bin/logs web` để xem lỗi đầy đủ. Nếu máy chủ cần proxy để kết nối tới GitHub, hãy đặt `GITHUB_SYNC_PROXY_URL`. > [accordion] Tôi có nên tắt “Expire user access tokens” trong GitHub OAuth App không? > > **Trả lời:** Có. Đồng bộ GitHub không gia hạn các token đã hết hạn. Khi bật token có thời hạn, người dùng sẽ phải kết nối lại GitHub mỗi khi token của họ hết hạn. > [accordion] Phiên bản của tôi có cần truy cập được từ internet không? > > **Trả lời:** Không. Việc liên kết tài khoản diễn ra thông qua trình duyệt của người dùng, vì vậy địa chỉ callback OAuth chỉ cần mở được trong trình duyệt của người dùng. Máy chủ chỉ cần kết nối được tới GitHub; nếu cần proxy để làm điều đó, hãy đặt `GITHUB_SYNC_PROXY_URL`. GitHub không bao giờ gọi tới phiên bản của bạn: một dự án chỉ được đồng bộ khi người dùng đồng bộ nó trong trình soạn thảo. > [accordion] Liên kết tài khoản GitHub của tôi thất bại hoặc đưa tôi quay lại mà không liên kết > > **Trả lời:** Hãy kiểm tra lần lượt các mục sau: > > * Mở Overleaf tại đúng địa chỉ được đặt trong `OVERLEAF_SITE_URL`. GitHub đưa bạn quay lại `${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback`, và phiên đăng nhập của bạn chỉ tồn tại trên địa chỉ bạn bắt đầu, vì vậy một host, IP hoặc cổng khác sẽ dẫn đến trang đăng nhập hoặc thông báo “Restricted, sorry you don’t have permission to load this page”. > * **Authorization callback URL** của OAuth App phải là `${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback`, với cùng scheme, host và cổng. > * Trang lỗi có `Failed to obtain access token from Git server` nghĩa là GitHub không trả về token: hãy kiểm tra `GITHUB_SYNC_CLIENT_ID` và `GITHUB_SYNC_CLIENT_SECRET`, và đảm bảo máy chủ có thể kết nối tới GitHub. Chạy `bin/logs web` để xem toàn bộ lỗi. > > Sau khi thay đổi `config/variables.env`, chạy `bin/up` để tạo lại các container. > [accordion] Nhập kho lưu trữ thất bại với “EmptyZipFileError: empty\_zip\_file” hoặc “unzip failed” > > **Trả lời:** Overleaf nhập tệp zip của commit mới nhất trên nhánh mặc định của kho lưu trữ, và lỗi này nghĩa là tệp zip đó không có tệp nào Overleaf có thể nhập. Hãy kiểm tra nhánh mặc định trên GitHub: > > * Nhánh chứa các tệp dự án, chứ không chỉ các tệp mà Overleaf bỏ qua khi nhập: các dotfile như `.gitignore` và `.gitmodules` (`.latexmkrc` vẫn được giữ), và các tệp build như `*.aux`, `*.log`, `*.bbl`, `*.synctex.gz`, `*.doc` và `*.docx`. > * Các tệp không chỉ nằm trong Git submodule. Tệp nén của GitHub để các submodule thành thư mục trống. > * Các tệp bạn mong đợi nằm trên nhánh mặc định, không phải trên một nhánh khác. Việc nhập luôn dùng nhánh mặc định. > [accordion] Nhập kho lưu trữ thất bại với “connect ECONNREFUSED” tới “sharelatex:3054” > > **Trả lời:** `V1_HISTORY_URL` được đặt thành `http://sharelatex:3054`, một giá trị mà các phiên bản cũ của tài liệu này đã đưa ra. Cổng `3054` là dịch vụ `project-history`, chỉ lắng nghe bên trong container, trong khi `V1_HISTORY_URL` phải trỏ tới `history-v1`. Overleaf lưu mọi tệp nhị phân (hình ảnh, PDF) của kho lưu trữ được nhập vào `history-v1`, vì vậy việc nhập thất bại; tải lên một tệp như vậy trong trình soạn thảo cũng thất bại theo cách tương tự. Trong `docker-compose.yml` của bạn, đặt `V1_HISTORY_URL: "http://sharelatex:3100/api"` trên dịch vụ `sharelatex` (xem [Tích hợp Git](https://ayakaleaf-pro.mintlify.site/vi/on-premises/configuration/overleaf-toolkit/integrations/git-integration.md)) và tạo lại container. Toolkit đã đặt sẵn giá trị này; hãy kiểm tra rằng `docker-compose.override.yml` không ghi đè nó. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.