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

> [!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). Tính năng được giới thiệu trong v6.3.2 dưới dạng bản xem trước sớm (early preview) và sẽ được phát hành chính thức trong v6.4.0, vì vậy cấu hình và hành vi của tính năng vẫn có thể thay đổi. 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 Gitea hoạt động giống như [đồng bộ hóa GitHub](https://ayakaleaf-pro.mintlify.site/vi/on-premises/configuration/overleaf-toolkit/github-synchronisation.md) và [đồng bộ hóa GitLab](https://ayakaleaf-pro.mintlify.site/vi/on-premises/configuration/overleaf-toolkit/gitlab-synchronisation.md): người dùng liên kết tài khoản Gitea của mình, xuất dự án sang các kho lưu trữ Gitea mới, nhập các kho lưu trữ Gitea và đồng bộ thay đổi theo cả hai chiều. Tính năng hoạt động với Gitea từ phiên bản 1.23 trở lên, trên gitea.com hoặc trên phiên bản của riêng bạn.

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

> [!WARNING]
>
> Bạn cần bật [git-bridge](https://ayakaleaf-pro.mintlify.site/vi/on-premises/configuration/overleaf-toolkit/git-integration.md) trước khi sử dụng đồng bộ hóa Gitea.
>
> ```dotenv title="config/overleaf.rc" theme={null}
> GIT_BRIDGE_ENABLED=true
> ```

Tạo một ứng dụng OAuth2 trên phiên bản Gitea của bạn, trong *Settings → Applications → Manage OAuth2 applications* (hoặc *Site Administration → Integrations → Applications* đối với ứng dụng dùng cho toàn bộ phiên bản):

* **Application name**: ví dụ `Overleaf`, người dùng sẽ thấy tên này khi họ cấp quyền cho ứng dụng
* **Redirect URIs**: `${OVERLEAF_SITE_URL}/user/gitea-sync/oauth2/callback`
* **Confidential client**: được chọn

Sao chép **Client ID** và **Client Secret**, 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 Gitea access and refresh tokens.
# How to generate: `openssl rand -hex 32`
GITEA_TOKEN_CIPHER_PASSWORD=0123456789ABCDEFG # changed to yours

# Gitea Sync Settings
GITEA_SYNC_ENABLED=true
GITEA_SYNC_CLIENT_ID=
GITEA_SYNC_CLIENT_SECRET=

# Web address of your Gitea (its ROOT_URL), defaults to https://gitea.com
# GITEA_SYNC_URL=https://gitea.example.com

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

> [!WARNING]
>
> Trước khi cấu hình redirect URI của Gitea, hãy đảm bảo `OVERLEAF_SITE_URL` đã được đặt chính xác.

Overleaf yêu cầu mọi quyền mà việc đồng bộ cần ngay khi người dùng liên kết tài khoản, vì vậy người dùng không bao giờ phải liên kết lại vì thiếu quyền:

| Scope | Dùng cho |
| - | - |
| `write:repository` | Các kho lưu trữ, tệp của chúng (bao gồm cả các CI workflow trong `.gitea/workflows`), các nhánh và pull request |
| `write:user` | Tạo kho lưu trữ của người dùng khi xuất dự án (Gitea yêu cầu scope này cho `POST /user/repos`) |
| `write:organization` | Liệt kê các tổ chức của người dùng và tạo kho lưu trữ của một tổ chức khi xuất dự án |

Gitea hiển thị các scope này khi người dùng cấp quyền cho ứng dụng, và giới hạn token trong phạm vi các scope đó.

Access token của Gitea hết hạn sau một giờ (`[oauth2] ACCESS_TOKEN_EXPIRATION_TIME`). Overleaf làm mới chúng bằng refresh token mà Gitea cấp kèm theo, kể cả khi Gitea vô hiệu hóa refresh token sau khi sử dụng (`INVALIDATE_REFRESH_TOKENS = true`), 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 Gitea.

### Phiên bản Gitea của bạn

Đặt `GITEA_SYNC_URL` thành địa chỉ web của phiên bản của bạn, tức là `ROOT_URL` của nó, địa chỉ bạn dùng để mở các kho lưu trữ trong trình duyệt. REST API được suy ra từ địa chỉ này:

| Biến | Mặc định |
| - | - |
| `GITEA_SYNC_URL` | `https://gitea.com` |
| `GITEA_SYNC_API_URL` | `${GITEA_SYNC_URL}/api/v1` |

Gitea được phục vụ dưới một đường dẫn con cũng hoạt động, ví dụ `GITEA_SYNC_URL=https://example.com/gitea`. Chỉ đặt `GITEA_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.

> [!WARNING]
>
> * Hãy tạo ứng dụng OAuth2 trên phiên bản mà bạn đặt trong `GITEA_SYNC_URL`, ứng dụng từ một phiên bản khác sẽ không hoạt động.
> * `GITEA_SYNC_URL` chỉ là địa chỉ web. Không thêm `/api/v1` hoặc đường dẫn người dùng hay tổ chức.
> * Overleaf commit bằng file API của Gitea, vốn cần đến trình soạn thảo web: hãy giữ `[repository.editor]` ở trạng thái bật (mặc định).

> [!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/gitea-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 `GITEA_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 Gitea 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 Gitea. Hãy đặt biến môi trường sau: `GITEA_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ữ Gitea. 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ữ Gitea mới | Chủ sở hữu dự án |
| Nhập một kho lưu trữ Gitea 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 Gitea bằng tài khoản Gitea 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 Gitea 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 Gitea cho dự án.
* Việc hủy liên kết tài khoản trong Overleaf sẽ xóa token của tài khoản đó; Gitea không có API để thu hồi token, vì vậy nếu muốn, bạn hãy thu hồi quyền đã cấp trong *Settings → Applications* của Gitea.

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

* **Quyền**: người dùng cần được phép push lên nhánh mặc định của kho lưu trữ đã liên kết. Khi một quy tắc bảo vệ nhánh không cho phép người dùng 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 Gitea, 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 pull request với kiểu hợp nhất mặc định của kho lưu trữ, vì Gitea không có API để hợp nhất các nhánh mà không cần pull request. Sau khi hợp nhất, Overleaf xóa nhánh tạm thời; pull request đã hợp nhất vẫn được giữ lại trong kho lưu trữ như một bản ghi.
* **Quy tắc hợp nhất**: Overleaf không bao giờ bỏ qua cơ chế bảo vệ nhánh của kho lưu trữ. Khi pull request có xung đột, hoặc cần được phê duyệt hay cần các status check 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 Gitea, sau đó tiếp tục đồng bộ.
* **CI workflow**: Overleaf không hiển thị các dotfile như `.gitea/workflows/` và giữ nguyên chúng trong kho lưu trữ. Các commit từ Overleaf khởi chạy Gitea Actions như mọi commit khác.

### 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, ví dụ bằng một quy tắc bảo vệ nhánh. Overleaf có thể tiếp quản một nhánh đã bị viết lại, nhưng đồng bộ hóa Gitea đượ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.

> **Đồng bộ hóa Gitea có hỗ trợ Git LFS không?**
>
> **Trả lời:** Không. Các dự án Overleaf không hỗ trợ Git Large File Storage. Các tệp được Git LFS theo dõi sẽ xuất hiện trong Overleaf dưới dạng tệp con trỏ LFS, chứ không phải nội dung của chúng. Thay vào đó, hãy commit trực tiếp hình ảnh và tệp PDF vào kho lưu trữ.

> **Tính năng này có hoạt động với kho lưu trữ SHA-256 không?**
>
> **Trả lời:** Chưa. Overleaf so sánh các tệp theo ID SHA-1 của chúng, vì vậy trong một kho lưu trữ được tạo với định dạng đối tượng SHA-256, mỗi lần pull sẽ ghi lại toàn bộ tệp, kể cả những tệp không thay đổi. Không có gì bị mất, nhưng vui lòng sử dụng định dạng SHA-1 mặc định.

> **Tính năng này có hoạt động với Forgejo không?**
>
> **Trả lời:** Đồng bộ hóa Gitea chỉ được xây dựng và kiểm thử với Gitea.


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