Workflow Git untuk Tim Laravel - Standardisasi Branch, Migration, dan CI/CD

Mengelola basis kode Laravel dalam tim pengembang sering kali menghadirkan tantangan teknis tersendiri. Seiring bertambahnya anggota tim dan tingginya frekuensi rilis fitur, masalah seperti bentrok migrasi database, konflik pada file composer.lock, format kode yang tidak konsisten, hingga kebocoran file konfigurasi lingkungan (environment variables) menjadi kendala harian yang berulang.

Artikel ini membahas penyusunan workflow Git terstruktur yang dirancang khusus untuk proyek Laravel. Pembahasan mencakup strategi penataan cabang (branching strategy), teknik menyelesaikan bentrok migrasi dan dependensi, pengamanan file sensitif, otomatisasi validasi lokal menggunakan Husky v9, hingga otomatisasi pengujian berbasis GitHub Actions.

1. Strategi Cabang (Git Branching Strategy) & Penanganan Konflik Kode

Pemilihan strategi cabang harus disesuaikan dengan skala tim dan model rilis aplikasi. Untuk pengembangan aplikasi web skala menengah hingga besar dengan Laravel, kombinasi antara Trunk-Based Development dan GitHub Flow terbukti lebih efisien dibandingkan Git Flow klasik yang mempertahankan banyak cabang berumur panjang (long-lived branches).

Struktur Cabang

• main (atau master): Memuat kode siap rilis ke lingkungan produksi (production-ready). Setiap komit yang masuk ke cabang ini wajib lulus seluruh tahapan integrasi pada pipeline CI/CD.
• staging / develop (opsional): Digunakan sebagai lingkungan pengujian integrasi gabungan sebelum kode dipindahkan ke main.
• feature/<nama-fitur>: Cabang berumur pendek (short-lived) yang dibuat khusus untuk menyelesaikan satu tugas fitur, perbaikan bug, atau refactoring.

Konvensi Penamaan Cabang

Gunakan awalan yang konsisten agar tujuan pembuatan cabang langsung teridentifikasi:

• Fitur baru: feature/user-authentication atau feat/user-auth
• Perbaikan bug: fix/payment-gateway-timeout atau bugfix/cart-calculation
• Pembaruan struktur/refactoring: refactor/optimize-user-query
• Perbaikan darurat produksi: hotfix/security-patch-v1.2

Command Praktis Workflow Cabang

Saat akan memulai pengerjaan fitur baru, pastikan cabang utama di komputer lokal selalu selaras dengan repositori remote:

# Update cabang main lokal dari remote
git checkout main
git pull origin main

# Buat cabang fitur baru dari main
git checkout -b feature/order-management

Setelah penulisan kode fitur selesai, lakukan penggabungan kembali ke cabang utama melalui Pull Request (PR) atau Merge Request (MR). Gunakan pendekatan rebase untuk menjaga riwayat komit tetap linear.

Resolusi Bentrok File Spesifik Laravel

1. Konflik pada composer.lock

Konflik pada file composer.lock sering terjadi ketika dua developer menambahkan atau mengunduh paket Composer berbeda di cabang masing-masing pada waktu bersamaan.

Jangan pernah menyelesaikan konflik composer.lock secara manual dengan menyunting blok teks <<<<<<< HEAD di dalam file JSON tersebut. Langkah aman untuk menyelesaikannya adalah:

# Tarik perubahan terbaru dari main ke dalam cabang fitur
git fetch origin
git rebase origin/main

# Jika terjadi bentrok pada composer.lock, ambil versi composer.lock dari cabang target (main)
git checkout origin/main -- composer.lock

# Jalankan update/install untuk meregenerasi lockfile secara otomatis sesuai composer.json gabungan
composer install

# Tandai konflik selesai dan lanjutkan rebase
git add composer.lock composer.json
git rebase --continue

2. Konflik pada .env.example

Ketika anggota tim menambahkan variabel lingkungan baru (misalnya STRIPE_SECRET=), pastikan perubahan tersebut dimasukkan ke file .env.example. Jika terjadi konflik saat penggabungan cabang, pertahankan seluruh baris kunci baru yang dibutuhkan oleh kedua fitur, lalu komunikasikan kepada tim agar setiap developer memperbarui file .env lokal masing-masing.

2. Penanganan Bentrok Migrasi Database (Migration Collision)

Salah satu masalah paling sering dialami tim pengembang Laravel adalah bentrok stempel waktu migrasi (migration timestamp collision). Masalah ini terjadi ketika dua developer membuat file migrasi baru di cabang berbeda pada hari yang sama, kemudian menggabungkannya ke cabang utama.

Mengapa Bentrok Migrasi Berbahaya?

Perhatikan skenario berikut:

• Developer A membuat migrasi: 2026_09_23_080000_add_status_to_orders_table.php
• Developer B membuat migrasi: 2026_09_23_080500_create_order_items_table.php

Jika Developer A mengacu pada tabel order_items yang dibuat oleh Developer B (misalnya menambahkan foreign key constraint), tetapi file migrasi Developer A memiliki stempel waktu lebih awal daripada Developer B, maka eksekusi php artisan migrate pada lingkungan bersih (seperti CI server atau server produksi) akan gagal karena tabel order_items belum dibuat saat migrasi Developer A dijalankan.

Solusi Praktis Penanganan Migrasi

1. Gunakan Rebase Sebelum Pengajuan PR
   Sebelum membuka Pull Request, jalankan git rebase origin/main. Jika urutan migrasi tampak membingungkan atau bergantung pada tabel yang baru dibuat di main, ubah stempel waktu nama file migrasi Kamu secara manual agar urutannya berurutan dengan benar.

2. Schema Dumping dengan php artisan schema:dump (Laravel 8+)
   Seiring berjalannya proyek selama bertahun-tahun, direktori database/migrations dapat berisikan ratusan file migrasi. Sejak Laravel 8, Laravel menyediakan fitur schema dumping untuk memadatkan struktur basis data ke dalam satu file skema SQL.

   Jalankan perintah berikut:

   # Mengisi skema basis data ke database/schema/mysql-schema.sql (atau postgres-schema.sql)
   php artisan schema:dump
   
   # Mengisi skema SQL SEKALIGUS menghapus file migrasi lama dari disk
   php artisan schema:dump --prune
   

   Peringatan Penting mengenai --prune: Flag --prune akan menghapus secara permanen seluruh file migrasi yang ada di direktori database/migrations dan menggantikannya dengan satu file skema di folder database/schema/. Jangan gunakan --prune jika tim Kamu masih membutuhkan riwayat file migrasi individu untuk keperluan penelusuran historis. Jika --prune digunakan, pastikan perubahan tersebut di-commit ke Git. Saat php artisan migrate dijalankan di lingkungan baru, Laravel akan mengeksekusi file skema SQL terlebih dahulu, lalu menjalankan sisa file migrasi baru yang dibuat setelah dump tersebut.

3. Verifikasi Migrasi Lokal Secara Bersih
   Sebelum melakukan push, pastikan skema basis data dapat dibangun ulang dari awal tanpa error:

   php artisan migrate:fresh --seed
   

3. Pengamanan File Sensitif dan Konfigurasi .gitignore

Kebocoran kunci rahasia (secret keys), kredensial basis data, atau token API ke repositori Git publik maupun privat merupakan risiko keamanan serius. Pengaturan .gitignore yang tepat adalah garis pertahanan pertama aplikasi.

Konfigurasi .gitignore Standar Laravel Modern

Pastikan file .gitignore di akar proyek Laravel mencakup direktori build, cache, dan seluruh variasi file konfigurasi lingkungan local/testing:

/vendor
/node_modules
/public/build
/public/storage
/storage/*.key
/storage/app/*
!/storage/app/.gitignore
/storage/framework/cache/*
/storage/framework/sessions/*
/storage/framework/views/*
/storage/logs/*
!/storage/logs/.gitignore

# Keamanan File Environment
.env
.env.*
!.env.example

# File Konfigurasi IDE dan Tooling
/.idea
/.vscode
*.suo
*.ntvs*
*.njsproj
*.sln
*.sw?

# Cache Pengujian
.phpunit.result.cache
.pest-cache
Homestead.json
Homestead.yaml
auth.json
npm-debug.log
yarn-error.log

Catatan: Pola .env.* sangat krusial untuk mencegah berkas seperti .env.local, .env.testing, atau .env.staging terikut ke dalam komit Git secara tidak sengaja, sambil tetap mengecualikan .env.example (!.env.example) agar template konfigurasi tetap terlacak.

Penanganan Berkas Sensitif yang Terlanjur Ter-commit

Jika file .env terlanjur masuk ke dalam lacakan Git, menghapusnya dengan git rm biasa tidak cukup karena file tersebut masih tersimpan di dalam sejarah komit (commit history).

Langkah penanganan yang benar:

1. Hapus File dari Indeks Git:

   git rm --cached .env
   git commit -m "fix: remove .env from tracking"
   

2. Bersihkan Riwayat Git (Opsional namun Disarankan):
   Gunakan perkakas seperti git filter-repo atau BFG Repo-Cleaner untuk menghapus Jejak file .env dari seluruh sejarah komit repositori jika repositori bersifat publik.

3. Rotasi Kredensial (WAJIB):
   git rm --cached tidak menghapus isi data sensitif yang sudah pernah ter-push ke server remote. Asumsikan seluruh kunci rahasia di dalam file tersebut sudah terekspos. Segera ubah APP_KEY, kata sandi database, API secret, dan token akses yang pernah tercantum di dalamnya.

4. Automasi Lokal dengan Git Hooks (Husky v9, Laravel Pint, & Pest)

Mengandalkan kesadaran manual setiap developer untuk memformat kode dan menjalankan unit test sebelum melakukan commit sering kali tidak efektif. Dengan memanfaatkan Git Hooks, kita dapat memastikan bahwa kode yang tidak sesuai standar akan otomatis ditolak oleh Git di komputer lokal.

Pengaturan Git Hooks Menggunakan Husky v9

Pada Husky v9, mekanisme inisialisasi dan struktur file hook telah diperbarui menjadi lebih sederhana. Husky v9 tidak lagi menggunakan skrip pembungkus shell legacy (. "$(dirname "$0")/_/husky.sh").

Langkah 1: Instalasi Husky v9

Jalankan perintah berikut pada terminal proyek:

npm install husky --save-dev
npx husky init

Perintah npx husky init akan secara otomatis:

• Menambahkan skrip "prepare": "husky" pada file package.json.
• Membuat folder .husky/ beserta contoh file hook .husky/pre-commit.

Langkah 2: Konfigurasi File .husky/pre-commit

Buka file .husky/pre-commit dan sesuaikan isinya dengan skrip pengujian berbasis Laravel Pint dan Pest (atau PHPUnit):

echo "==> Running Laravel Pint (Code Style Checker)..."
./vendor/bin/pint --test

if [ $? -ne 0 ]; then
  echo "❌ Error: Format kode tidak sesuai standar! Jalankan './vendor/bin/pint' untuk memformat kode secara otomatis."
  exit 1
fi

echo "==> Running Pest Test Suite..."
./vendor/bin/pest --bail

if [ $? -ne 0 ]; then
  echo "❌ Error: Pengujian Pest gagal! Perbaiki pengujian sebelum melakukan commit."
  exit 1
fi

Cara Kerja Pre-Commit Hook

Ketika developer menjalankan perintah git commit -m "feat: add user profile", Git akan mengeksekusi skrip .husky/pre-commit terlebih dahulu:

1. Perintah ./vendor/bin/pint --test akan memeriksa apakah ada kode PHP yang melanggar aturan pengkodean (code style).
2. Jika Pint menemukan pelanggaran, proses komit akan langsung dibatalkan (exit 1).
3. Jika Pint lolos, Pest akan menjalankan seluruh test suite dengan opsi --bail (langsung berhenti begitu ada 1 tes yang gagal).
4. Komit baru akan berhasil dibuat hanya jika kedua tahap pengujian tersebut lulus.

5. Integrasi Continuous Integration (CI/CD) dengan GitHub Actions

Meskipun Git Hooks lokal sudah terpasang, developer masih bisa melompati pengecekan lokal (misalnya menggunakan flag git commit --no-verify). Oleh karena itu, server perantara seperti GitHub Actions berfungsi sebagai penentu utama (gatekeeper) sebelum kode diizinkan masuk ke cabang main.

Konfigurasi File .github/workflows/ci.yml

Buat file alur kerja GitHub Actions pada jalur .github/workflows/ci.yml:

name: Laravel CI

on:
  push:
    branches: [ "main", "develop" ]
  pull_request:
    branches: [ "main", "develop" ]

jobs:
  laravel-tests:
    runs-on: ubuntu-latest

    services:
      mysql:
        image: mysql:8.0
        env:
          MYSQL_DATABASE: testing_db
          MYSQL_ALLOW_EMPTY_PASSWORD: "yes"
        ports:
          - 3306:3306
        options: --health-cmd="mysqladmin ping" --health-interval=10s --health-timeout=5s --health-retries=3

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

    - name: Setup PHP Environment
      uses: shivammathur/setup-php@v2
      with:
        php-version: '8.3'
        extensions: mbstring, dom, fileinfo, mysql, pdo, pdo_mysql
        coverage: none

    - name: Copy Environment File
      run: php -r "file_exists('.env') || copy('.env.example', '.env');"

    - name: Install Composer Dependencies
      run: composer install -q --no-ansi --no-interaction --no-scripts --no-progress --prefer-dist

    - name: Generate Application Key
      run: php artisan key:generate

    - name: Set Directory Permissions
      run: chmod -R 777 storage bootstrap/cache

    - name: Check Code Formatting (Laravel Pint)
      run: ./vendor/bin/pint --test

    - name: Run Test Suite (Pest)
      env:
        DB_CONNECTION: mysql
        DB_HOST: 127.0.0.1
        DB_PORT: 3306
        DB_DATABASE: testing_db
        DB_USERNAME: root
        DB_PASSWORD: ""
      run: ./vendor/bin/pest

Penjelasan Detail Alur Kerja CI

1. Event Triggers (on): Pipeline akan berjalan secara otomatis saat ada komit baru (push) atau saat Pull Request dibuka menuju cabang main atau develop.
2. Service Container (MySQL): Menjalankan kontainer MySQL 8.0 terisolasi di dalam runner GitHub Actions untuk memfasilitasi pengujian yang membutuhkan basis data nyata.
3. Pemasangan Dependensi (composer install -q): Flag -q (atau --quiet) digunakan untuk menyembunyikan log output yang terlalu panjang tanpa menyebabkan kegagalan perintah (berbeda dengan flag --q yang tidak valid di Composer).
4. Pemisahan Lingkungan Dependencies (dev vs production): Pada runner CI, kita menjalankan composer install tanpa flag --no-dev karena perkakas pengujian seperti Pest dan Pint didaftarkan di dalam bagian require-dev pada file composer.json. Flag --no-dev hanya digunakan saat melakukan build akhir untuk deployment ke server produksi.
5. Validasi Mutlak: Apabila pemeriksaan format kode Pint atau pengujian Pest menghasilkan eror, status akumulatif GitHub Actions akan bertanda merah (failed), secara otomatis mengunci tombol Merge Pull Request pada repositori.

Penutup

Untuk mempermudah adopsi workflow ini oleh seluruh pengembang di dalam tim, berikut adalah daftar periksa (checklist) urutan kerja harian yang disarankan:

1. Awal Tugas: Always update main lokal dan buat cabang baru berbasis konvensi (git checkout -b feature/nama-fitur).
2. Pengerjaan Kode: Tambahkan variabel lingkungan baru ke .env.example jika ada penambahan konfigurasi.
3. Pengujian Lokal: Manfaatkan Husky v9 untuk memastikan pint dan pest lulus sebelum membuat komit.
4. Sebelum Pull Request: Lakukan git fetch origin dan git rebase origin/main untuk menyelaraskan urutan komit dan migrasi database.
5. Penyelesaian Bentrok: Selesaikan konflik composer.lock melalui pengunduhan ulang dependensi (composer install), bukan menyunting file JSON manual.
6. Integrasi Remote: Buka Pull Request ke main dan pastikan seluruh status check di GitHub Actions menunjukkan warna hijau sebelum di-merge.

Dengan menerapkan standardisasi workflow Git, penanganan migrasi yang aman, serta automatisasi pengujian berjenjang ini, tim pengembang Laravel dapat menekan jumlah bug di produksi, menghindari konflik basis data, dan menjaga kecepatan rilis perangkat lunak secara konsisten.

Referensi

• Dokumentasi Resmi Laravel - Migrations
• Dokumentasi Resmi Husky v9
• GitHub Actions for PHP Development