DocsAplikasi

Preview pull request

Setiap pull request mendapat container dan subdomain sendiri, dibuat saat PR dibuka dan dihapus saat ditutup.

Per PR: Satu container + satu subdomain
Hidup: Dari PR dibuka sampai ditutup/merge
Default: Mati — opt-in per aplikasi

Prasyarat

Webhook aplikasi terdaftar dengan event Pull requests (GitHub) atau Merge request events (GitLab), selain push.
Reverse proxy berjalan dengan PROXY_ACME_EMAIL bila ingin HTTPS.
Record DNS wildcard ke server:

DNS

*.preview.example.com.   A   203.0.113.10

Dengan koneksi Cloudflare dan DNS-01 pada proxy, Anda juga bisa memakai satu sertifikat wildcard untuk semua preview — lihat DNS Cloudflare. Record DNS wildcard ini tetap Anda buat sendiri.

Aplikasi berjalan di host aoox (bukan server remote).

Siklus hidup

01PR dibukarow preview dibuat, build dari branch PR
02runningcontainer <app>-pr<N> dilayani di <app>-pr<N>.<domain>
03push ke PRbuild ulang, container diganti
04PR ditutup / mergecontainer & row dihapus

Contoh: aplikasi shop, PR #42, preview domain preview.example.com

container : aoox-app-shop-pr42
router    : shop-pr42
host      : https://shop-pr42.preview.example.com

Mengaktifkan

Pengaturan aplikasi → Preview pull request
Nyalakan toggle dan isi Preview domain, mis. preview.example.com. Kosong = memakai env PREVIEW_DOMAIN di API (bila diset). Untuk mengisinya sekali untuk semua aplikasi, tulis PREVIEW_DOMAIN=preview.example.com di .env.dist lalu docker compose up -d. Instalasi yang dibuat sebelum variabel ini diteruskan ke container API belum menerimanya sampai aoox reinstall dijalankan — aoox update panel tidak menulis ulang file compose.
Buka pull request di provider
Webhook menerima event, aoox membangun branch PR dengan cara build yang sama (Dockerfile/Nixpacks) dan tag khusus preview.
Pantau di tab Webhook → Preview pull request
Daftar preview: nomor PR, status (building → running | failed), host + tautan buka, log build, dan tombol hapus manual. Daftar menyegarkan tiap 5 detik selama ada yang building.

Event yang ditangani

Provider	Membuat / menyegarkan	Menghapus	Diabaikan
GitHub (pull_request)	opened, synchronize, reopened	closed	PR dari fork (head repo ≠ base repo)
GitLab (merge_request)	open, update, reopen	close, merge	MR dari fork (source project ≠ target project)

Respons webhook untuk event ini: preview, preview-closed, atau ignored dengan reason (previews disabled, fork, preview limit).

Apa yang diwarisi dari aplikasi

Aspek	Preview
Cara build, Dockerfile path, build args	Sama
Environment variables (+ referensi project/database)	Sama — termasuk database produksi bila direferensikan
Health check path	Sama; deployment preview gagal bila tidak healthy
Batas CPU / memori	Sama
Mount (volume/bind/file)	Tidak — preview tanpa mount
Port host	Tidak — hanya lewat Traefik
Domain aplikasi	Tidak — host preview sendiri
Blue/green	Tidak — replace biasa
Metrik & notifikasi	Tidak ditampilkan di UI

Env dibagi dengan produksi

Preview memakai env aplikasi apa adanya. Bila env merujuk ${{database.<slug>.url}}, branch PR menulis ke database yang sama dengan produksi. Untuk isolasi, buat database terpisah dan pakai env berbeda, atau jangan aktifkan preview pada aplikasi yang memodifikasi data.

Aturan keamanan

Opt-in per aplikasi (default mati) — branch PR adalah kode arbitrer yang akan dijalankan di server-mu.
PR dari fork selalu diabaikan, walau preview aktif.
Maksimal 5 preview terbuka per aplikasi (PREVIEW_MAX); PR keenam mendapat ignored sampai ada yang ditutup.
PR yang ditutup saat build masih berjalan: container tidak ditinggalkan — dicek lagi setelah build dan setelah start.
Menghapus aplikasi ikut menghapus semua container preview PR-nya (juga di server remote).

Jebakan umum

Gejala	Penyebab & solusi
Webhook 200 ignored: previews disabled	Toggle belum dinyalakan di Pengaturan aplikasi.
Host preview tidak resolve	DNS wildcard belum ada, atau preview domain salah ketik.
Sertifikat error / lama terbit	ACME per host diminta saat pertama diakses. Untuk banyak PR, pakai `PROXY_ACME_STAGING=true` dulu agar tidak kena rate limit.
Preview running tapi 404 dari Traefik	Container belum healthy, atau health check gagal — lihat log build/preview.
Preview tidak muncul untuk PR tertentu	PR dari fork, atau sudah 5 preview terbuka.

Belum tersedia

Preview untuk aplikasi di server remote; komentar otomatis berisi tautan preview di PR; env khusus preview.

Langkah berikutnya

Webhook auto-deployPrasyarat: webhook dengan event PR/MR.Proxy & domainTraefik dan sertifikat untuk host preview.Deploy & rollbackHealth check yang juga dipakai preview.MonitoringBatas sumber daya yang diwarisi preview.

Ada yang keliru? Edit halaman ini di GitHub ↗

Pengaturan aplikasi → Preview pull request

Buka pull request di provider

Pantau di tab Webhook → Preview pull request