Sinkronisasi GitHub

Izinkan pengguna menyinkronkan proyek mereka dengan repositori GitHub atau GitHub Enterprise.

Fitur ini dikembangkan oleh ayaka-notes/ayakaleaf-pro, dimodifikasi oleh yu-i-i/overleaf-cep. Fitur ini diperkenalkan sejak v6.2.0 dan versi selanjutnya, dan masih berstatus beta. Kami membutuhkan masukan Anda jika Anda mengalami masalah.

​

Menyiapkan Sinkronisasi GitHub

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

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Kunjungi developers settings untuk membuat aplikasi OAuth GitHub Anda, lalu salin CLIENT_ID dan SECRET Anda.

Catatan: saat Anda membuat OAuth App, masukkan ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback di Authorization callback URL. Ayakaleaf Pro membangun alamat yang sama dari OVERLEAF_SITE_URL, sehingga tidak ada yang perlu diatur untuknya di config/variables.env.

Kemudian, tambahkan pengaturan berikut ke file variabel lingkungan Overleaf Anda.

config/variables.env

# 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

Sebelum mengonfigurasi URL callback OAuth GitHub, pastikan OVERLEAF_SITE_URL sudah diatur dengan benar.

Jika Anda berada di wilayah dengan akses jaringan yang dibatasi, Anda mungkin perlu mengonfigurasi proxy untuk mengakses GitHub. Atur variabel lingkungan berikut: GITHUB_SYNC_PROXY_URL=http://10.0.0.1:10808. Pastikan penggunaan proxy Anda mematuhi hukum dan peraturan setempat.

GITHUB_SYNC_PROXY_URL harus berupa forward proxy HTTP/HTTPS standar (misalnya port HTTP dari Clash). Mirror unduhan GitHub seperti gh-proxy.org tidak didukung.

Jangan gunakan 127.0.0.1 sebagai host proxy. Jika proxy berjalan di server host, gunakan alamat IP LAN server (seperti 192.168.1.xx) dan pastikan proxy dikonfigurasi untuk menerima koneksi dari perangkat di jaringan lokal.

​

GitHub Enterprise

Dukungan GitHub Enterprise diperkenalkan sejak v6.3.1 dan versi selanjutnya. Versi sebelumnya hanya terhubung ke github.com, dan variabel di bawah ini tidak berpengaruh.

Secara default, Sinkronisasi GitHub terhubung ke github.com. Untuk menggunakan GitHub Enterprise Server (self-hosted) atau GitHub Enterprise Cloud dengan data residency (GHE.com), atur GITHUB_SYNC_URL ke alamat web instans Anda, yaitu alamat yang Anda gunakan untuk membuka repositori di browser.

config/variables.env

# GitHub Enterprise Server
GITHUB_SYNC_URL=https://github.example.com

# or GitHub Enterprise Cloud with data residency
# GITHUB_SYNC_URL=https://octocorp.ghe.com

Endpoint REST API dan GraphQL API diturunkan dari GITHUB_SYNC_URL dengan cara yang sama seperti yang dilakukan GitHub CLI:

GITHUB_SYNC_URL	REST API	GraphQL API
https://github.com (default)	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 (lainnya)	https://HOST/api/v3	https://HOST/api/graphql

Atur endpoint API hanya jika instans Anda menyajikannya di tempat lain, misalnya di belakang API gateway:

Variabel	Default
GITHUB_SYNC_URL	https://github.com
GITHUB_SYNC_API_URL	Diturunkan dari GITHUB_SYNC_URL, lihat tabel di atas
GITHUB_SYNC_GRAPHQL_URL	Diturunkan dari GITHUB_SYNC_API_URL jika variabel tersebut diatur (/api/v3 menjadi /api/graphql, jika tidak /graphql ditambahkan di akhir), selain itu dari GITHUB_SYNC_URL

• Buat aplikasi OAuth di instans enterprise Anda (Settings → Developer settings → OAuth Apps); aplikasi dari github.com tidak berfungsi di sana. URL callback-nya sama: ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback.
• GITHUB_SYNC_URL hanya berupa alamat web. Jangan mengaturnya ke alamat API seperti https://api.github.com atau https://HOST/api/v3, dan jangan tambahkan path organisasi.
• Ketiga alamat harus mengarah ke instans GitHub yang sama.

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/github-ca.pem.

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

​

Siapa yang dapat menautkan dan menyinkronkan

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

Tindakan	Siapa yang dapat melakukannya
Mengekspor proyek ke repositori GitHub baru	Pemilik proyek
Mengimpor repositori GitHub 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 GitHub menggunakan akun GitHub milik pengguna yang melakukan sinkronisasi, sehingga setiap kolaborator yang menyinkronkan menautkan akun GitHub mereka sendiri, dan harus diizinkan melakukan push ke branch default repositori.
• Kolaborator dengan akses hanya-lihat tidak dapat menggunakan Sinkronisasi GitHub untuk proyek tersebut.

​

Q&A

Bagaimana cara menautkan proyek ke GitHub dan menyinkronkannya?

Jawaban: Di editor, buka Integrations dan klik GitHub. Jika akun GitHub Anda belum ditautkan, klik Link to your GitHub account terlebih dahulu. Di Export Project to GitHub, masukkan nama repositori, pilih Private di bawah Repository visibility, lalu klik Create a GitHub repository.

Setelah itu, kartu yang sama akan membuka Sync with GitHub, yang menampilkan daftar commit baru di GitHub. Klik Sync untuk meng-commit perubahan Overleaf Anda ke branch default dan membawa perubahan GitHub ke dalam proyek. Sinkronisasi berjalan dua arah, tetapi hanya dijalankan saat seseorang mengklik Sync; tidak ada sinkronisasi terjadwal. Jika kedua sisi berubah, Overleaf melakukan merge melalui branch sementara bernama overleaf-YYYY-MM-DD-HHMMSS. Jika merge tersebut mengalami konflik, lakukan merge branch tersebut sendiri di GitHub, lalu klik I have manually merged. Continue.

Bisakah saya melakukan force push ke branch default?

Jawaban: Kami tidak menyarankannya. Overleaf mendeteksi force push, memberikan peringatan, dan mengambil alih branch yang ditulis ulang, sambil menggabungkan perubahan yang dibuat di Overleaf sejak sinkronisasi terakhir. Untuk menghindari hal tak terduga, lindungi branch default dari force push di pengaturan repositori.

Bisakah saya mengganti nama branch default dari proyek yang ditautkan?

Jawaban: Harap jangan lakukan itu. Overleaf terus melakukan sinkronisasi dengan branch tempat proyek ditautkan. Untuk menyinkronkan dengan branch lain, putuskan tautan proyek, lalu impor repositori ke proyek baru, yang akan menggunakan branch default saat ini.

Sinkronisasi GitHub menampilkan "Something wrong with GitHub request"

Jawaban: Pesan ini berarti server tidak dapat menjangkau GitHub, misalnya karena masalah jaringan, DNS, TLS, atau proxy. Jalankan bin/logs web untuk melihat error lengkapnya. Jika server memerlukan proxy untuk menjangkau GitHub, atur GITHUB_SYNC_PROXY_URL.

Haruskah saya menonaktifkan "Expire user access tokens" di GitHub OAuth App?

Jawaban: Ya. Sinkronisasi GitHub tidak memperbarui token yang kedaluwarsa. Jika token kedaluwarsa diaktifkan, pengguna harus menghubungkan GitHub lagi setiap kali token mereka kedaluwarsa.

Apakah instans saya perlu dapat dijangkau dari internet?

Jawaban: Tidak. Penautan akun dilakukan melalui browser pengguna, sehingga alamat callback OAuth hanya perlu dapat dibuka di browser pengguna. Server hanya perlu menjangkau GitHub; jika memerlukan proxy untuk itu, atur GITHUB_SYNC_PROXY_URL. GitHub tidak pernah memanggil instans Anda: proyek hanya disinkronkan saat pengguna menyinkronkannya di editor.

Menautkan akun GitHub saya gagal atau mengembalikan saya tanpa menautkan

Jawaban: Periksa hal-hal berikut secara berurutan:

• Buka Overleaf di alamat persis yang diatur di OVERLEAF_SITE_URL. GitHub mengembalikan Anda ke ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback, dan login Anda hanya ada di alamat tempat Anda memulai, sehingga host, IP, atau port lain akan berakhir di halaman login atau di “Restricted, sorry you don’t have permission to load this page”.
• Authorization callback URL dari OAuth App harus ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback, dengan skema, host, dan port yang sama.
• Halaman error dengan Failed to obtain access token from Git server berarti GitHub tidak mengembalikan token: periksa GITHUB_SYNC_CLIENT_ID dan GITHUB_SYNC_CLIENT_SECRET, serta pastikan server dapat menjangkau GitHub. Jalankan bin/logs web untuk melihat error lengkapnya.

Setelah mengubah config/variables.env, jalankan bin/up untuk membuat ulang container.

Impor repositori gagal dengan “EmptyZipFileError: empty_zip_file” atau “unzip failed”

Jawaban: Overleaf mengimpor arsip zip dari commit terbaru di branch default repositori, dan error ini berarti arsip tersebut tidak berisi file yang dapat diimpor oleh Overleaf. Periksa branch default di GitHub:

• Branch tersebut berisi file proyek, bukan hanya file yang dilewati Overleaf saat impor: dotfile seperti .gitignore dan .gitmodules (.latexmkrc tetap disertakan), serta file build seperti *.aux, *.log, *.bbl, *.synctex.gz, *.doc, dan *.docx.
• File-file tersebut tidak hanya berada di dalam Git submodule. Arsip GitHub membiarkan submodule sebagai folder kosong.
• File yang Anda harapkan berada di branch default, bukan di branch lain. Impor selalu menggunakan branch default.

Impor repositori gagal dengan “connect ECONNREFUSED” ke “sharelatex:3054”

Jawaban: V1_HISTORY_URL diatur ke http://sharelatex:3054, nilai yang diberikan oleh versi lama dokumentasi ini. Port 3054 adalah layanan project-history, yang hanya mendengarkan di dalam container, sedangkan V1_HISTORY_URL harus mengarah ke history-v1. Overleaf menyimpan setiap file biner (gambar, PDF) dari repositori yang diimpor ke history-v1, sehingga impor gagal; mengunggah file semacam itu di editor juga gagal dengan cara yang sama. Di docker-compose.yml Anda, atur V1_HISTORY_URL: "http://sharelatex:3100/api" pada layanan sharelatex (lihat Integrasi Git) dan buat ulang container. Toolkit sudah mengatur nilai ini; periksa bahwa docker-compose.override.yml tidak menimpanya.