#Cara Deploy Laravel dengan GitHub Actions Sederhana

Deploy Laravel dengan GitHub Actions memungkinkan setiap push ke branch utama menjalankan proses deploy otomatis ke VPS. Jawaban cepatnya: siapkan SSH key deploy, simpan secret di GitHub, buat workflow yang login ke server, pull kode terbaru, install dependency, migrate, build asset, cache config, dan restart queue worker.

Untuk pemula, GitHub Actions bukan pengganti memahami deploy manual. Sebaiknya kamu bisa deploy Laravel ke VPS secara manual dulu, baru mengotomatisasi langkah yang sudah terbukti benar.

#Kapan Perlu GitHub Actions?

GitHub Actions cocok jika:

• project sudah disimpan di GitHub
• deploy manual mulai sering dilakukan
• kamu ingin mengurangi lupa langkah deploy
• ada beberapa orang yang mengerjakan project
• kamu ingin menjalankan lint/test sebelum deploy
• server sudah stabil dengan Nginx, PHP-FPM, database, dan .env production

Jika project masih latihan lokal, GitHub Actions belum wajib. Fokus dulu memahami Cara Deploy Laravel ke VPS.

#Alur Deploy Sederhana

Alur yang akan dibuat:

Push ke main
  -> GitHub Actions berjalan
  -> login SSH ke VPS
  -> git pull
  -> composer install
  -> npm ci && npm run build
  -> php artisan migrate --force
  -> cache config/route/view
  -> php artisan queue:restart

Workflow ini cocok untuk project kecil sampai menengah. Untuk aplikasi besar, biasanya ada proses build artifact, zero-downtime deploy, health check, dan rollback yang lebih matang.

#Prasyarat di Server

Pastikan server sudah bisa deploy manual:

cd /var/www/toko-laravel
git pull origin main
composer install --no-dev --optimize-autoloader
npm ci
npm run build
php artisan migrate --force
php artisan optimize

Pastikan juga:

• Nginx mengarah ke folder public
• file .env production sudah ada di server
• database production sudah benar
• permission storage dan bootstrap/cache sudah aman
• queue worker memakai Supervisor jika project memakai queue

Untuk permission server, baca Permission Folder Storage Laravel di Linux.

#Buat SSH Key untuk Deploy

Di laptop atau mesin aman, buat SSH key khusus deploy:

ssh-keygen -t ed25519 -C "github-actions-deploy" -f github-actions-deploy

Perintah ini menghasilkan:

github-actions-deploy
github-actions-deploy.pub

Tambahkan public key ke server:

ssh-copy-id -i github-actions-deploy.pub deploy@IP_SERVER

Atau salin isi github-actions-deploy.pub ke:

/home/deploy/.ssh/authorized_keys

Test login:

ssh -i github-actions-deploy deploy@IP_SERVER

Gunakan user deploy khusus jika memungkinkan. Hindari deploy sebagai root.

#Simpan Secret di GitHub

Di repository GitHub, buka:

Settings -> Secrets and variables -> Actions -> New repository secret

Buat secret:

Jangan menyimpan isi .env production di workflow jika tidak perlu. Untuk setup sederhana, .env tetap berada di server dan tidak masuk Git.

#Contoh Workflow GitHub Actions

Buat file:

.github/workflows/deploy.yml

Isi contoh:

name: Deploy Laravel

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Deploy via SSH
        uses: appleboy/ssh-action@v1.2.0
        with:
          host: ${{ secrets.VPS_HOST }}
          username: ${{ secrets.VPS_USER }}
          key: ${{ secrets.VPS_SSH_KEY }}
          port: ${{ secrets.VPS_PORT }}
          script: |
            set -e
            cd ${{ secrets.PROJECT_PATH }}
            git pull origin main
            composer install --no-dev --optimize-autoloader
            npm ci
            npm run build
            php artisan migrate --force
            php artisan config:cache
            php artisan route:cache
            php artisan view:cache
            php artisan queue:restart

Workflow ini menjalankan perintah di server. Artinya server tetap membutuhkan Git, Composer, Node.js, PHP, dan akses repository.

#Tambahkan Lint atau Test Sebelum Deploy

Jika project punya test, jalankan sebelum step deploy:

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.3'

      - name: Install PHP dependencies
        run: composer install --no-interaction --prefer-dist

      - name: Run tests
        run: php artisan test

Untuk project yang memakai frontend:

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install Node dependencies
        run: npm ci

      - name: Build assets
        run: npm run build

Jika test gagal, deploy tidak dilanjutkan. Ini lebih aman daripada server menerima kode yang belum lolos pengecekan dasar.

#Checklist Setelah Deploy Otomatis

Setelah workflow berhasil, cek:

php artisan about
php artisan migrate:status
php artisan queue:failed
sudo supervisorctl status

Buka halaman penting:

• homepage
• login
• form utama
• halaman upload file
• halaman yang membaca database
• API endpoint jika ada

Jika project memakai scheduler, pastikan cron tetap berjalan. GitHub Actions tidak menggantikan Scheduler Laravel di Production.

#Kesalahan yang Sering Terjadi

#Private Key Salah Format

Secret VPS_SSH_KEY harus berisi private key lengkap, termasuk baris pembuka dan penutup. Jangan isi dengan public key.

#Deploy Berjalan sebagai root

Deploy sebagai root bisa membuat file hasil deploy dimiliki root, lalu PHP-FPM gagal menulis cache atau log. Gunakan user deploy dan atur permission dengan benar.

#Workflow Menghapus .env

Jangan menjalankan perintah yang menimpa .env production tanpa sengaja. File .env sebaiknya tetap dikelola di server atau lewat secret management yang jelas.

#npm run build Gagal di Server

Pastikan Node.js tersedia di server dan versi Node cocok dengan project. Jika build asset terlalu berat untuk server kecil, pertimbangkan build di GitHub Actions lalu kirim artifact.

#Lupa queue:restart

Jika project memakai queue, worker lama bisa tetap menjalankan kode lama. Tambahkan:

php artisan queue:restart

Supervisor akan menjalankan worker lagi.

#Pencegahan

1. Pastikan deploy manual stabil sebelum membuat workflow.
2. Gunakan SSH key khusus deploy, bukan key pribadi utama.
3. Simpan secret hanya di GitHub Actions secrets.
4. Jalankan test sebelum deploy jika tersedia.
5. Gunakan set -e agar workflow berhenti saat satu perintah gagal.
6. Dokumentasikan perintah deploy yang dijalankan otomatis.
7. Cek permission setelah deploy pertama dari GitHub Actions.

#Bacaan Terkait

• Cara Deploy Laravel ke VPS
• Laravel .env Production: Checklist Aman
• Permission Folder Storage Laravel di Linux
• Setup Supervisor untuk Queue Laravel
• Cara Menjalankan Scheduler Laravel di Production

#FAQ

#Apakah GitHub Actions gratis untuk deploy Laravel?

GitHub menyediakan kuota Actions untuk banyak repository, tetapi batas dan kebijakan bisa berubah. Untuk project kecil, workflow deploy sederhana biasanya ringan.

#Apakah .env production perlu disimpan di GitHub Secrets?

Tidak wajib. Untuk setup sederhana, .env tetap berada di server. Simpan di GitHub Secrets hanya jika kamu punya proses yang jelas untuk membuat file .env saat deploy.

#Apakah workflow ini zero-downtime?

Belum. Workflow sederhana ini cukup untuk belajar dan project kecil, tetapi masih bisa ada jeda saat dependency, migration, atau build berjalan.

#Kenapa deploy berhasil tetapi website error 500?

Cek storage/logs/laravel.log, permission folder, .env, hasil migration, dan apakah cache config sudah sesuai. Error deploy otomatis tetap harus dibaca dari log.

#Bolehkah deploy otomatis langsung dari semua branch?

Sebaiknya tidak. Untuk pemula, batasi deploy ke branch main agar push eksperimen tidak langsung masuk production.