$ aoox

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
  • Aplikasi berjalan di host aoox (bukan server remote).

Siklus hidup

  1. 01PR dibukarow preview dibuat, build dari branch PR
  2. 02runningcontainer <app>-pr<N> dilayani di <app>-pr<N>.<domain>
  3. 03push ke PRbuild ulang, container diganti
  4. 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

  1. Pengaturan aplikasi → Preview pull request

    Nyalakan toggle dan isi Preview domain, mis. preview.example.com. Kosong = memakai env PREVIEW_DOMAIN di API (bila diset).

  2. Buka pull request di provider

    Webhook menerima event, aoox membangun branch PR dengan cara build yang sama (Dockerfile/Nixpacks) dan tag khusus preview.

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

ProviderMembuat / menyegarkanMenghapusDiabaikan
GitHub (pull_request)opened, synchronize, reopenedclosedPR dari fork (head repo ≠ base repo)
GitLab (merge_request)open, update, reopenclose, mergeMR 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

AspekPreview
Cara build, Dockerfile path, build argsSama
Environment variables (+ referensi project/database)Sama — termasuk database produksi bila direferensikan
Health check pathSama; deployment preview gagal bila tidak healthy
Batas CPU / memoriSama
Mount (volume/bind/file)Tidak — preview tanpa mount
Port hostTidak — hanya lewat Traefik
Domain aplikasiTidak — host preview sendiri
Blue/greenTidak — replace biasa
Metrik & notifikasiTidak 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.

Jebakan umum

GejalaPenyebab & solusi
Webhook 200 ignored: previews disabledToggle belum dinyalakan di Pengaturan aplikasi.
Host preview tidak resolveDNS wildcard belum ada, atau preview domain salah ketik.
Sertifikat error / lama terbitACME 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 TraefikContainer belum healthy, atau health check gagal — lihat log build/preview.
Preview tidak muncul untuk PR tertentuPR 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 GitLab ↗