Auto Deploy

Cara kerja Auto Deploy

Auto Deploy me-redeploy aplikasi GitHub setiap kali GitHub mengirim push event untuk branch yang dilacak aplikasi. Server Compass memasang gateway yang selalu aktif dan deployment worker privat di server Anda, membuat webhook repository, memverifikasi signed test delivery dari GitHub, dan mengantrekan commit yang tepat untuk deployment.

Aplikasi desktop Server Compass tidak perlu tetap terbuka setelah penyiapan. Runtime sisi server memulai ulang bersama Docker dan terus menerima webhook, mem-build aplikasi, serta mencatat riwayat deployment. Port SSH Anda dapat tetap privat; hanya hostname webhook yang harus dapat dijangkau oleh GitHub melalui HTTPS.

Persyaratan

Sebelum memulai, pastikan Anda memiliki:

• Aplikasi Docker yang sudah di-deploy dari repository GitHub
• Build on VPS dipilih sebagai lokasi build; build GitHub Actions tidak didukung oleh webhook Auto Deploy v1
• Git checkout terkelola di dalam direktori Server Compass milik aplikasi
• Akun GitHub tertaut dengan izin untuk membuat webhook repository
• Docker Engine dan Docker Compose di server
• Hostname HTTPS publik khusus seperti deploy.example.com
• Rute dari hostname tersebut ke webhook gateway

Auto Deploy mengikuti branch yang disimpan pada aplikasi yang di-deploy. Setiap push ke branch yang tepat itu mengantrekan commit yang disertakan dalam event GitHub; push ke branch lain diabaikan.

Menyiapkan aplikasi

1. Di Server Compass, deploy repository sebagai aplikasi GitHub.
2. Pilih Build on VPS selama deployment.
3. Buka aplikasi yang di-deploy dan masuk ke Deployments.
4. Temukan kartu Auto Deploy dan klik Set up Auto Deploy.
5. Masukkan hostname webhook publik. Gunakan hanya hostname atau HTTPS origin, misalnya deploy.example.com atau https://deploy.example.com. Jangan menambahkan path, query string, atau port khusus.

Hostname adalah pintu masuk publik untuk GitHub. Domain saja tidak cukup: DNS, TLS, aturan firewall atau NAT, serta proxy atau tunnel Anda harus membentuk rute lengkap ke gateway di server.

Pilih cara GitHub menjangkau server

Ketiga opsi rute menggunakan signed webhook dan deployment worker privat yang sama. Hanya rute publiknya yang berbeda.

Server Compass-managed Traefik

Gunakan ini ketika Server Compass-managed Traefik sudah menjadi reverse proxy publik di server. Arahkan record DNS hostname ke server dan pastikan port inbound 80 dan 443 dapat menjangkaunya. Server Compass memasang webhook gateway ke jaringan Docker traefik-public yang sudah ada dan mengonfigurasi rute host HTTPS.

Ini biasanya opsi paling sederhana untuk VPS publik. Ini juga dapat bekerja untuk server LAN ketika router meneruskan port 80 dan 443 ke server tersebut dan hostname me-resolve ke IP publik router.

Existing reverse proxy

Gunakan ini ketika Nginx, Caddy, Traefik, HAProxy, atau proxy lain sudah menangani hostname. Klik Check server untuk mendapatkan loopback target yang dihasilkan, lalu rutekan hostname webhook ke alamat yang ditampilkan, misalnya http://127.0.0.1:42315.

Proxy harus mempertahankan raw request body dan header webhook GitHub agar gateway dapat memverifikasi HMAC signature. Jangan menempatkan login middleware, Cloudflare Access, atau halaman autentikasi interaktif lain di depan rute ini.

Jika proxy berjalan di Docker, ingat bahwa 127.0.0.1 di dalam container proxy merujuk ke container tersebut. Gunakan host networking, alamat host-gateway, atau jaringan Docker bersama yang sesuai sebagai gantinya.

Stable tunnel

Gunakan ini untuk server LAN, VPS privat, koneksi CGNAT, atau server mana pun yang tidak ingin Anda buka port inbound-nya. Buat named Cloudflare Tunnel persisten atau tunnel setara, jalankan connector-nya di server, dan petakan hostname publik ke loopback target yang ditampilkan oleh Check server, seperti http://127.0.0.1:42315.

Tunnel harus stabil dan mulai secara otomatis setelah reboot. Quick Tunnel sementara atau URL ngrok yang berubah saat di-restart tidak cocok karena GitHub menyimpan URL webhook. Jika connector berjalan di Docker, berikan host networking atau rute lain yang benar-benar dapat menjangkau gateway di host.

Periksa server dan aktifkan

1. Klik Check server.
2. Pastikan Docker Engine, Docker Compose, dan port gateway yang disarankan lolos pemeriksaan kesiapan.
3. Jika Anda memilih managed Traefik, pastikan jaringan traefik-public juga lolos.
4. Jika Anda memilih proxy yang ada atau stable tunnel, selesaikan rute eksternal ke port loopback yang tepat yang ditampilkan di hasil.
5. Klik Activate Auto Deploy.

Server Compass memasang gateway dan worker, membuat URL webhook privat, menyimpan signing secret di server, membuat webhook di GitHub, mengirim ping GitHub, dan menunggu signed delivery yang berhasil. Status berjalan melalui Installed, Routed, Hooked, Verified, dan Active.

Jika penyiapan berhenti di Awaiting route, runtime sudah terpasang tetapi GitHub belum dapat menjangkaunya. Selesaikan atau perbaiki rute DNS, TLS, firewall/NAT, proxy, atau tunnel, lalu klik Continue setup. Anda tidak perlu memasang ulang aplikasi.

Verifikasi Auto Deploy

Pertama, pastikan health endpoint publik menjangkau gateway Server Compass:

curl -fsS https://deploy.example.com/healthz

Kemudian verifikasi keseluruhan alur deployment:

1. Di GitHub, buka repository dan masuk ke Settings > Webhooks.
2. Buka webhook yang dibuat Server Compass dan pastikan delivery terbarunya mengembalikan respons 2xx.
3. Push commit kecil ke branch yang dilacak.
4. Di Server Compass, buka riwayat deployment aplikasi dan pastikan job webhook menggunakan commit yang di-push.
5. Pastikan aplikasi yang di-deploy berisi perubahan tersebut.

Untuk pengujian terakhir, keluar sepenuhnya dari Server Compass, push commit lain ke branch yang dilacak, dan verifikasi aplikasi kembali. Deployment seharusnya tetap selesai karena gateway, antrean, dan worker berjalan di server.

Kelola webhook aktif

Kartu Auto Deploy menyediakan tindakan berikut:

• Test webhook mengirim test delivery GitHub lagi dan menyegarkan statusnya.
• Rotate secret mengganti signing secret di server maupun di webhook GitHub.
• Pause mempertahankan target dan riwayat tetapi menghentikan deployment otomatis; Resume mengaktifkannya kembali.
• Remove menghapus webhook GitHub dan remote target policy-nya sambil tetap menyimpan riwayat deployment.

Untuk mengubah repository atau branch yang dilacak, Remove Auto Deploy terlebih dahulu, perbarui dan deploy ulang aplikasi dengan repository atau branch baru, lalu siapkan Auto Deploy lagi.

Pemecahan masalah dan keamanan

• Health endpoint gagal atau mengembalikan 502/404: verifikasi DNS dan TLS, pastikan proxy atau tunnel mengarah ke port loopback saat ini, dan pastikan container gateway berjalan.
• Delivery GitHub bukan 2xx: periksa delivery terbaru webhook, pastikan tidak ada lapisan autentikasi yang memblokir GitHub, dan pastikan proxy tidak mengubah raw body atau menghapus header GitHub.
• Push tidak melakukan deploy: pastikan Auto Deploy berstatus Active, bukan Paused, dan push dilakukan ke branch yang tepat yang dilacak.
• Tunnel bekerja sampai reboot: konfigurasikan named tunnel connector sebagai system service atau container yang dapat di-restart. Jangan gunakan URL sementara.
• Desktop tertutup dan deployment gagal: periksa bahwa server online dan container gateway serta worker Server Compass berjalan.

URL webhook berisi private route token dan tidak boleh dipublikasikan. Delivery GitHub diautentikasi dengan HMAC signing secret yang dibuat dan disimpan di server serta tidak pernah ditampilkan di UI. Anda tidak perlu mengekspos SSH, Docker socket, atau worker privat ke internet.