Webhook auto-deploy

Pemicu

Push ke branch aplikasi

Endpoint

POST <PUBLIC_API_URL>/webhooks/<token>

Keamanan

Token di URL + secret HMAC opsional

Prasyarat

• PUBLIC_API_URL bisa dijangkau dari internet — GitHub/GitLab memanggilnya dari luar. IP publik + port 3001, atau domain via Domain untuk panel.
• Aplikasi sudah pernah di-deploy sekali secara manual (registry, build, dsb. sudah beres).

Alur

1. 01pushgit push origin main
2. 02providerGitHub/GitLab memanggil Webhook URL
3. 03verifikasitoken URL (+ tanda tangan bila secret aktif)
4. 04deploydiantrekan seperti tombol Deploy

Kredensial Git (repo privat)

Dibutuhkan agar daemon Docker (dan helper Nixpacks) bisa meng-clone repo privat. Tidak berhubungan dengan webhook masuk, tapi biasanya diatur bersamaan.

1. Buat token di provider

   Provider	Jenis token	Scope minimum
   GitHub	Fine-grained atau classic PAT	Classic: repo. Fine-grained: Contents → Read.
   GitLab	Project/Personal access token	read_repository
   Generik	Username + password/token HTTP basic	Akses baca

2. Settings → Kredensial Git → Kredensial Git baru (owner/admin)

   Pilih Provider, isi Username dan Password / token. Token disimpan terenkripsi (ENCRYPTION_KEY) dan tidak ditampilkan lagi.

3. Pilih di form aplikasi

   Select Kredensial Git di Pengaturan aplikasi. URL repo tetap ditulis tanpa user:token@ — aoox menyusunnya sendiri saat build dan menyensor token di log.

• Menghapus kredensial melepasnya dari aplikasi yang memakainya; build berikutnya gagal bila repo privat.
• Untuk GitHub fine-grained token, pastikan repo-nya termasuk dalam daftar akses token.

Mengaktifkan webhook

1. Salin Webhook URL dari tab Webhook

   https://api.panel.example.com/webhooks/9f3a1c…e21d

   Token 32 byte acak, unik per aplikasi. Buat ulang kapan saja — URL lama langsung tidak berlaku.

2. Daftarkan di provider

   GitHub

   Field	Nilai
   Payload URL	Webhook URL
   Content type	application/json
   Secret	Isi bila secret diaktifkan (langkah berikutnya)
   Events	Just the push event; tambah Pull requests untuk preview

   GitLab

   Field	Nilai
   URL	Webhook URL
   Secret token	Isi bila secret diaktifkan
   Trigger	Push events; tambah Merge request events untuk preview

3. Uji: push ke branch aplikasi

   Deployment baru muncul di tab Deploy beberapa detik setelah push. Di provider, halaman Recent Deliveries menampilkan respons API — lihat tabel di bawah untuk membacanya.

Membaca respons webhook

Secret (tanda tangan)

Tanpa secret, siapa pun yang tahu URL bisa memicu deploy (bukan mengubah kode — hanya membangun ulang branch yang sama). Untuk menutupnya, di bagian Secret (tanda tangan):

1. Klik aktifkan, salin nilai secret

   Ditampilkan di tab Webhook selama aktif supaya bisa disalin ulang.

2. Tempel di provider

   • GitHub: field Secret → header X-Hub-Signature-256 = sha256=HMAC-SHA256(secret, raw body).
   • GitLab: field Secret token → header X-Gitlab-Token = secret apa adanya.

3. Kirim ulang delivery terakhir dari provider

   Harus 200. Bila 401, secret di provider tidak cocok.

• Rotasi membuat nilai baru — perbarui di provider sebelum push berikutnya.
• Nonaktifkan kembali ke perilaku token-URL saja.
• Perbandingan memakai timingSafeEqual; HMAC dihitung atas byte body persis, bukan JSON hasil parse.

Jebakan umum

Langkah berikutnya