Đồng bộ hóa GitLab

Tính năng này được phát triển bởi ayaka-notes/ayakaleaf-pro. Tính năng được giới thiệu từ v6.4.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.

Đồng bộ hóa GitLab hoạt động giống như đồng bộ hóa GitHub: người dùng liên kết tài khoản GitLab của mình, xuất dự án sang các dự án GitLab mới, nhập các kho lưu trữ GitLab và đồng bộ thay đổi theo cả hai chiều. Tính năng hoạt động với GitLab.com và với GitLab tự quản lý phiên bản 15.10 trở lên (Community Edition và Enterprise Edition).

​

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

Bạn cần bật git-bridge trước khi sử dụng đồng bộ hóa GitLab.

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Tạo một ứng dụng OAuth trên phiên bản GitLab của bạn, trong User settings → Applications (hoặc Admin area → Applications đối với ứng dụng dùng cho toàn bộ phiên bản):

• Redirect URI: ${OVERLEAF_SITE_URL}/user/gitlab-sync/oauth2/callback
• Confidential: được chọn
• Scopes: api

Sao chép Application ID và Secret, 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

# used to encrypt the user's GitLab access and refresh tokens.
# How to generate: `openssl rand -hex 32`
GITLAB_TOKEN_CIPHER_PASSWORD=0123456789ABCDEFG # changed to yours

# GitLab Sync Settings
GITLAB_SYNC_ENABLED=true
GITLAB_SYNC_CLIENT_ID=
GITLAB_SYNC_CLIENT_SECRET=

# Web address of your GitLab, defaults to https://gitlab.com
# GITLAB_SYNC_URL=https://gitlab.example.com

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

Trước khi cấu hình redirect URI OAuth của GitLab, hãy đảm bảo OVERLEAF_SITE_URL đã được đặt chính xác.

Access token của GitLab hết hạn sau hai giờ. Overleaf làm mới chúng bằng refresh token mà GitLab cấp kèm theo, vì vậy người dùng vẫn được liên kết cho đến khi họ hủy liên kết hoặc thu hồi ứng dụng trong GitLab.

​

GitLab tự quản lý

Đặt GITLAB_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 dự án trong trình duyệt. REST API được suy ra từ địa chỉ này:

Biến	Mặc định
GITLAB_SYNC_URL	https://gitlab.com
GITLAB_SYNC_API_URL	${GITLAB_SYNC_URL}/api/v4

Chỉ đặt GITLAB_SYNC_API_URL khi phiên bản của bạn phục vụ API ở 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 mà bạn đặt trong GITLAB_SYNC_URL, ứng dụng từ gitlab.com sẽ không hoạt động trên phiên bản tự quản lý.
• GITLAB_SYNC_URL chỉ là địa chỉ web. Không thêm /api/v4 hoặc đường dẫn nhóm.

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/gitlab-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 GITLAB_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 GitLab và các dự án của họ.

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 GitLab. Hãy đặt biến môi trường sau: GITLAB_SYNC_PROXY_URL=http://10.0.0.1:10808. Đây phải là một proxy chuyển tiếp HTTP/HTTPS tiêu chuẩn và không được sử dụng 127.0.0.1.

​

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ữ GitLab. 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ữ GitLab mới	Chủ sở hữu dự án
Nhập một kho lưu trữ GitLab 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 GitLab bằng tài khoản GitLab 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 GitLab 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 GitLab cho dự án.

​

Cách đồng bộ hoạt động với GitLab

• Quyền: người dùng cần được phép push lên nhánh mặc định của dự án đã liên kết. Khi nhánh mặc định được bảo vệ và người dùng không được phép push lên đó, Overleaf sẽ yêu cầu họ liên hệ với chủ sở hữu dự án, giống như với một kho lưu trữ mà họ đã mất quyền truy cập.
• Hợp nhất: khi một dự án có thay đổi cả trong Overleaf và trong GitLab, Overleaf commit các thay đổi của mình vào một nhánh tạm thời có tên overleaf-YYYY-MM-DD-HHMMSS và hợp nhất nhánh đó thông qua một merge request, vì GitLab không có API để hợp nhất các nhánh mà không cần merge request. Sau khi hợp nhất, Overleaf xóa nhánh tạm thời và merge request. Trong GitLab, chỉ quản trị viên và chủ sở hữu dự án mới có thể xóa merge request, vì vậy đối với những người dùng khác, merge request đã hợp nhất sẽ vẫn còn trong dự án.
• Quy tắc hợp nhất: Overleaf không bao giờ bỏ qua các quy tắc hợp nhất của dự án. Khi merge request có xung đột, hoặc cần được phê duyệt hay cần một pipeline chạy thành công, nó sẽ vẫn mở và Overleaf sẽ yêu cầu người dùng hợp nhất nó trong GitLab, sau đó tiếp tục đồng bộ.
• Pipeline: các commit từ Overleaf khởi chạy pipeline như mọi commit khác. Nếu dự án của bạn chạy pipeline cho merge request và yêu cầu chúng phải thành công, các lần hợp nhất từ Overleaf sẽ chờ chúng, như đã mô tả ở trên.

​

Q&A

Tôi có thể force push lên nhánh mặc định không?

Trả lời: Vui lòng giữ tính năng force push lên nhánh mặc định ở trạng thái tắt. Đây là mặc định của GitLab: nhánh mặc định của một dự án mới được bảo vệ và không ai có thể force push lên đó. Overleaf có thể tiếp quản một nhánh đã bị viết lại, nhưng đồng bộ hóa GitLab được thiết kế cho một nhánh mặc định mà lịch sử chỉ tăng thêm.

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: Không. Overleaf tiếp tục đồng bộ với nhánh mà dự án đã được liên kết, vì vậy việc đồng bộ sẽ thất bại khi nhánh đó bị đổi tên hoặc bị xóa. Để đồ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.