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

# Sinkronisasi GitHub

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

> [!NOTE]
>
> Fitur ini dikembangkan oleh [ayaka-notes/ayakaleaf-pro](https://github.com/ayaka-notes/ayakaleaf-pro), dimodifikasi oleh [yu-i-i/overleaf-cep](https://github.com/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.

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-36.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=fd5305cbb4ea8505b5eab6f41f90a57c)

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-39.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=1d8103102915872ba94119bb00fa58e0)

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-35.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=18c0d0917b5c3768593a608a53b6c19c)

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-40.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=7ebf71a5528a1b22e1e2c7f17a71b49a)

### Menyiapkan Sinkronisasi GitHub

> [!WARNING]
>
> Anda perlu mengaktifkan [git-bridge](https://ayakaleaf-pro.mintlify.site/id/on-premises/configuration/overleaf-toolkit/integrations/git-integration.md) terlebih dahulu sebelum menggunakan Sinkronisasi GitHub.
>
> ```dotenv title="config/overleaf.rc" theme={null}
> GIT_BRIDGE_ENABLED=true
> ```

Kunjungi [developers settings](https://github.com/settings/developers) 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.

```dotenv title="config/variables.env" wrap theme={null}
# 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
```

> [!WARNING]
>
> 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.

> [!WARNING]
>
> `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.

> [!WARNING]
>
> 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

> [!NOTE]
>
> 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.

```dotenv title="config/variables.env" wrap theme={null}
# 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` |

> [!WARNING]
>
> * 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.

> [!NOTE]
>
> 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`.

> [!CAUTION]
>
> 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

> [accordion] 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**.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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`.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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](https://ayakaleaf-pro.mintlify.site/id/on-premises/configuration/overleaf-toolkit/integrations/git-integration.md)) dan buat ulang container. Toolkit sudah mengatur nilai ini; periksa bahwa `docker-compose.override.yml` tidak menimpanya.


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