Strategi Branch main/staging/api: Deploy Aman dengan Vercel Preview dan GitHub Actions

Masalahnya: push ke main langsung live

Begitu frontend tersambung ke Vercel, setiap push ke branch produksi otomatis di-promote dan domain utama langsung melayani versi terbaru. Perilaku ini adalah default resmi Vercel: menge-push atau me-merge ke production branch memicu deployment production, dan domain kustom langsung dipindahkan ke deployment terbaru saat build berhasil. Cepat dan nyaman — sampai satu commit bocor ke pengunjung karena belum sempat diuji.

Artikel ini merangkum model branch yang saya pakai di produksi untuk blog ini sendiri: tiga branch (main, staging, api) yang masing-masing punya satu tugas, frontend di Vercel, API di VPS via GitHub Actions. Model ini hasil evolusi setelah migrasi frontend ke Vercel — bukan teori dari dokumen saja.

Model tiga branch: satu sumber kebenaran, dua pointer deploy

Inti modelnya sederhana: hanya main yang berisi kode. Dua branch lainnya bukan tempat development, melainkan pointer ke commit tertentu di main:

• main — sumber kebenaran. Semua pekerjaan di-commit ke sini. Vercel menjadikannya production branch.
• staging — pointer untuk preview deployment Vercel. Push ke branch non-produksi apa pun otomatis dapat preview; branch ini dijadikan "stasiun uji" tetap.
• api — pointer yang memicu workflow GitHub Actions untuk deploy API ke VPS.

Karena keduanya hanya pointer, promosi selalu fast-forward — tidak pernah ada merge conflict, dan sejarah git tetap linear:

# uji frontend di preview sebelum live
git checkout staging && git merge --ff-only main && git push origin staging && git checkout main

# deploy API ke VPS
git checkout api && git merge --ff-only main && git push origin api && git checkout main

Pola "promosi = merge antar branch" ini sama dengan yang dipakai dunia GitOps: panduan promosi OneUptime, misalnya, mendeskripsikan urutan git checkout staging && git merge develop && git push origin staging sebagai cara standar memindahkan perubahan antar environment. Perbedaannya, di sini environment-nya bukan Kubernetes cluster melainkan Vercel preview dan VPS.

Catatan penting urutan di atas: push ke staging tidak membuat perubahan live. Domain produksi hanya berganti ketika main di-push. Jadi alur amannya terbalik dari intuisi awal banyak orang — merge ke main boleh duluan, karena yang menentukan kapan pengunjung melihat perubahan adalah push itu sendiri; staging tinggal di-fast-forward kapan pun butuh URL uji.

Cara Vercel memperlakukan branch Anda

Memahami dua aturan ini membuat seluruh model jadi masuk akal:

1. Satu branch produksi, sisanya preview. Sesuai dokumentasi Git Vercel, semua branch selain production branch diperlakukan sebagai preview branch. Push ke branch mana pun (atau membuka PR) menghasilkan deployment dengan URL otomatis.
2. Dua jenis URL preview. Vercel memberi URL spesifik-branch yang selalu menunjuk commit terbaru di branch itu (cocok untuk dibagikan saat review), dan URL spesifik-commit yang membekukan versi tertentu (cocok untuk melacak regresi).

Deployment pertama sebuah project selalu berstatus production, apa pun caranya — itu juga default dokumentasi. Setelah itu aturan preview berlaku normal: hanya branch produksi yang menyentuh domain utama.

Setup praktis

Yang perlu disiapkan di sisi Vercel hanya dua hal:

• Production branch diarahkan ke main (default, tinggal pastikan).
• Environment variables di-set untuk environment Production dan Preview — misalnya NEXT_PUBLIC_API_URL, NEXT_PUBLIC_SITE_URL. Vercel memang memisahkan variabel per environment; dokumentasinya menegaskan variabel preview tidak bisa dipakai di deployment production, jadi isi keduanya agar preview tidak jatuh ke fallback localhost.

Lalu buat branch pointernya sekali di awal:

git checkout main
git checkout -b staging && git push -u origin staging
git checkout main
git checkout -b api && git push -u origin api
git checkout main

Selesai. Tidak ada konfigurasi tambahan di Vercel untuk staging — mem-push branch non-produksi mana pun sudah otomatis menghasilkan preview.

Jalur API: GitHub Actions ke VPS

Backend tidak dihosting di Vercel, jadi branch api berperan sebagai pemicu CI/CD klasik. Workflow-nya dipicu push ke branch api (plus dispatch manual untuk ref spesifik: tag, branch, atau SHA), lalu menjalankan satu job deploy lewat SSH: menarik commit, membangun image Docker, health check endpoint /api/health, verifikasi versi build, dan auto-rollback bila gagal. Pola minimal trigger-nya:

on:
  push:
    branches: [api]
  workflow_dispatch:

Tag versi (vX.Y.Z) dipakai hanya saat ingin deploy ref lama yang spesifik — deploy harian cukup lewat fast-forward branch.

Alternatif: staged production deployment

Vercel menyediakan jalur uji kedua yang kurang dikenal: staged production deployment. Matikan opsi Auto-assign Custom Production Domains di Settings → Environments → Production, dan setiap push ke main tetap membangun deployment production — tetapi domain tidak otomatis pindah sampai Anda menekan Promote di dashboard. Dokumen setup staging di Vercel menjelaskan kedua opsi ini berdampingan.

Kapan pilih yang mana?

• Branch staging + preview — pas bila build yang diuji memakai environment variable berbeda, ingin URL stabil untuk QA, atau API juga ikut pola merge antar branch.
• Staged production — pas bila yang mau diverifikasi justru build production-nya (variabel produksi, domain asli) sebelumterbuka ke pengunjung, tanpa rebuild saat promote.

Keduanya tidak saling eksklusif; model saya memilih branch karena simetri dengan jalur api di VPS.

Posisi model ini di peta strategi branch

Dibanding pola klasik, model tiga pointer ini adalah varian ramping dari environment branches. Referensi umum menyebut empat keluarga besar: GitHub Flow (satu main, deploy tiap merge), GitFlow (develop + release + hotfix, untuk rilis berjadwal), GitLab Flow (branch per environment, perubahan mengalir satu arah), dan trunk-based development. Peta lengkapnya dirangkum DeployHQ dan panduan branching Azure Repos.

Titik bedanya: di GitLab Flow penuh, kode benar-benar dikembangkan dan distabilkan di tiap branch environment, sehingga merge conflict jadi risiko nyata. Di model pointer, branch environment tidak pernah menerima commit unik — git merge --ff-only bahkan akan menolak bila itu terjadi — jadi kompleksitas itu hilang total. Bayarannya: model ini hanya cocok bila satu versi live pada satu waktu, tanpa fase QA panjang terpisah. Untuk rilis berjadwal ala aplikasi mobile, GitFlow tetap lebih tepat.

Checklist ringkas

• Semua commit ke main; staging dan api hanya pointer fast-forward.
• Ingin URL uji: fast-forward staging dan push — ambil URL spesifik-branch dari dashboard.
• Deploy API: fast-forward api dan push; workflow Actions menjalankan build, health check, dan rollback otomatis.
• Perlu verifikasi build production sebelum live: matikan auto-assign domain dan pakai Promote.
• Jangan pernah commit langsung ke staging/api — pola --ff-only ada justru untuk memblokernya.

Model paling sederhana yang berhasil adalah model yang bisa dijelaskan dalam satu kalimat: main adalah kode, staging adalah "tunjukkan ke saya dulu", api adalah "jalankan sekarang".