Skip to main content
Tính năng này được phát triển bởi ayaka-notes/ayakaleaf-pro và được chỉnh sửa bởi 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.

​
Thiết lập đồng bộ hóa GitHub

Bạn cần bật git-bridge trước khi sử dụng đồng bộ hóa GitHub.
config/overleaf.rc
Truy cập developers settings để 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.
config/variables.env
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.
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ợ.
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

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.
config/variables.env
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: 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:
  • 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.
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.
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.
  • 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

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.
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ữ.
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.
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.
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.
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.
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.
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.
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) 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ó.
Lần sửa đổi cuối 2 tháng 11, 2026