Sinkronisasi Gitea

Fitur ini dikembangkan oleh ayaka-notes/ayakaleaf-pro. Fitur ini diperkenalkan di v6.3.2 sebagai pratinjau awal dan akan dirilis secara resmi di v6.4.0, sehingga konfigurasi dan perilakunya masih dapat berubah. Kami membutuhkan masukan Anda jika Anda mengalami masalah.

Sinkronisasi Gitea bekerja seperti Sinkronisasi GitHub dan Sinkronisasi GitLab: pengguna menautkan akun Gitea mereka, mengekspor proyek ke repositori Gitea baru, mengimpor repositori Gitea, dan menyinkronkan perubahan ke dua arah. Fitur ini berfungsi dengan Gitea 1.23 atau lebih baru, di gitea.com maupun di instans Anda sendiri.

​

Menyiapkan Sinkronisasi Gitea

Anda perlu mengaktifkan git-bridge terlebih dahulu sebelum menggunakan Sinkronisasi Gitea.

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Buat aplikasi OAuth2 di instans Gitea Anda, melalui Settings → Applications → Manage OAuth2 applications (atau Site Administration → Integrations → Applications untuk aplikasi tingkat instans):

• Application name: misalnya Overleaf, pengguna melihatnya saat mengotorisasi aplikasi
• Redirect URIs: ${OVERLEAF_SITE_URL}/user/gitea-sync/oauth2/callback
• Confidential client: dicentang

Salin Client ID dan Client Secret, lalu tambahkan pengaturan berikut ke file variabel lingkungan Overleaf Anda.

config/variables.env

# 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

Sebelum mengonfigurasi redirect URI Gitea, pastikan OVERLEAF_SITE_URL sudah diatur dengan benar.

Overleaf meminta semua yang dibutuhkan untuk sinkronisasi saat pengguna menautkan akun, sehingga pengguna tidak perlu menautkan ulang karena izin yang kurang:

Scope	Digunakan untuk
write:repository	Repositori, file-filenya (termasuk workflow CI di bawah .gitea/workflows), branch, dan pull request
write:user	Membuat repositori milik pengguna saat mengekspor (Gitea memintanya pada POST /user/repos)
write:organization	Menampilkan daftar organisasi pengguna dan membuat repositori milik salah satunya saat mengekspor

Gitea menampilkan scope ini saat pengguna mengotorisasi aplikasi, dan membatasi token hanya pada scope tersebut.

Token akses Gitea kedaluwarsa setelah satu jam ([oauth2] ACCESS_TOKEN_EXPIRATION_TIME). Overleaf memperbaruinya menggunakan refresh token yang diterbitkan Gitea bersamanya, juga ketika Gitea menghabiskan refresh token setelah digunakan (INVALIDATE_REFRESH_TOKENS = true), sehingga pengguna tetap tertaut hingga mereka memutuskan tautan atau mencabut aplikasi di Gitea.

​

Instans Gitea Anda

Atur GITEA_SYNC_URL ke alamat web instans Anda, yaitu ROOT_URL-nya, alamat yang Anda gunakan untuk membuka repositori di browser. REST API diturunkan dari alamat tersebut:

Variabel	Default
GITEA_SYNC_URL	https://gitea.com
GITEA_SYNC_API_URL	${GITEA_SYNC_URL}/api/v1

Gitea yang disajikan di bawah sub-path juga berfungsi, misalnya GITEA_SYNC_URL=https://example.com/gitea. Atur GITEA_SYNC_API_URL hanya jika instans Anda menyajikan API di tempat lain, misalnya di belakang API gateway.

• Buat aplikasi OAuth2 di instans yang Anda atur pada GITEA_SYNC_URL; aplikasi dari instans lain tidak berfungsi.
• GITEA_SYNC_URL hanya berupa alamat web. Jangan tambahkan /api/v1 atau path pengguna atau organisasi.
• Overleaf melakukan commit dengan file API Gitea, yang memerlukan editor web: biarkan [repository.editor] tetap aktif (default).

Jika instans Anda menggunakan sertifikat dari CA privat, mount sertifikat CA tersebut ke dalam kontainer dan arahkan NODE_EXTRA_CA_CERTS ke sertifikat itu, misalnya NODE_EXTRA_CA_CERTS=/var/lib/overleaf/certs/gitea-ca.pem.

Akun dan proyek yang ditautkan terikat pada instans tempat mereka ditautkan. Sebelum mengganti GITEA_SYNC_URL ke instans lain, minta pengguna untuk memutuskan tautan akun Gitea dan proyek mereka.

Jika Anda berada di wilayah dengan akses jaringan yang dibatasi, Anda mungkin perlu mengonfigurasi proxy untuk mengakses Gitea. Atur variabel lingkungan berikut: GITEA_SYNC_PROXY_URL=http://10.0.0.1:10808. Proxy tersebut harus berupa forward proxy HTTP/HTTPS standar, dan tidak boleh menggunakan 127.0.0.1.

​

Siapa yang dapat menautkan dan menyinkronkan

Seperti di Overleaf Cloud, hanya pemilik proyek yang dapat menautkan proyek ke repositori Gitea. Setelah ditautkan, setiap kolaborator dengan akses edit dapat menyinkronkannya.

Tindakan	Siapa yang dapat melakukannya
Mengekspor proyek ke repositori Gitea baru	Pemilik proyek
Mengimpor repositori Gitea ke proyek baru	Pengguna mana pun, yang kemudian menjadi pemilik proyek baru
Pull, push, dan merge proyek yang ditautkan	Pemilik dan kolaborator dengan akses edit
Memutuskan tautan proyek dari repositorinya	Pemilik proyek

• Overleaf berkomunikasi dengan Gitea menggunakan akun Gitea milik pengguna yang melakukan sinkronisasi, sehingga setiap kolaborator yang menyinkronkan menautkan akun Gitea mereka sendiri, dan harus diizinkan melakukan push ke branch default repositori.
• Kolaborator dengan akses hanya-lihat tidak dapat menggunakan Sinkronisasi Gitea untuk proyek tersebut.
• Memutuskan tautan akun di Overleaf akan melupakan tokennya; Gitea tidak memiliki API untuk mencabutnya, jadi cabut juga izinnya melalui Settings → Applications di Gitea jika Anda menginginkannya.

​

Cara kerja sinkronisasi dengan Gitea

• Izin: pengguna harus diizinkan melakukan push ke branch default repositori yang ditautkan. Jika aturan proteksi branch tidak mengizinkan pengguna melakukan push ke sana, Overleaf meminta mereka menghubungi pemilik proyek, sama seperti pada repositori yang aksesnya telah hilang.
• Merge: jika proyek berubah baik di Overleaf maupun di Gitea, Overleaf melakukan commit perubahannya ke branch sementara bernama overleaf-YYYY-MM-DD-HHMMSS dan menggabungkannya melalui pull request dengan gaya merge default repositori, karena Gitea tidak memiliki API untuk menggabungkan branch tanpa pull request. Setelah merge, Overleaf menghapus branch sementara; pull request yang sudah digabungkan tetap ada di repositori sebagai catatan.
• Aturan merge: Overleaf tidak pernah melewati proteksi branch repositori. Jika pull request mengalami konflik, atau memerlukan persetujuan atau pemeriksaan status yang berhasil, pull request tetap terbuka dan Overleaf meminta pengguna untuk menggabungkannya di Gitea, lalu melanjutkan sinkronisasi.
• Workflow CI: Overleaf tidak menampilkan dotfile seperti .gitea/workflows/, dan membiarkannya apa adanya di repositori. Commit dari Overleaf memicu Gitea Actions seperti commit lainnya.

​

Q&A

Bisakah saya melakukan force push ke branch default?

Jawaban: Harap biarkan force push ke branch default tetap dinonaktifkan, misalnya dengan aturan proteksi branch. Overleaf dapat mengambil alih branch yang ditulis ulang, tetapi Sinkronisasi Gitea dirancang untuk branch default yang riwayatnya hanya bertambah.

Bisakah saya mengganti nama branch default dari proyek yang ditautkan?

Jawaban: Tidak. Overleaf terus melakukan sinkronisasi dengan branch tempat proyek ditautkan, sehingga sinkronisasi akan gagal setelah branch tersebut diganti namanya atau dihapus. Untuk menyinkronkan dengan branch lain, putuskan tautan proyek, lalu impor repositori ke proyek baru, yang akan menggunakan branch default saat ini.

Apakah Sinkronisasi Gitea mendukung Git LFS?

Jawaban: Tidak. Proyek Overleaf tidak mendukung Git Large File Storage. File yang dilacak oleh Git LFS muncul di Overleaf sebagai file pointer LFS, bukan sebagai isinya. Sebagai gantinya, lakukan commit gambar dan PDF langsung ke repositori.

Apakah fitur ini berfungsi dengan repositori SHA-256?

Jawaban: Belum. Overleaf membandingkan file berdasarkan ID SHA-1-nya, sehingga pada repositori yang dibuat dengan format objek SHA-256, setiap pull menulis ulang semua file, termasuk yang tidak berubah. Tidak ada yang hilang, tetapi harap gunakan format SHA-1 default.

Apakah fitur ini berfungsi dengan Forgejo?

Jawaban: Sinkronisasi Gitea dibangun dan diuji hanya terhadap Gitea.