Jika tim Anda masih membuat rilis CodeIgniter 4 secara manual—mengubah versi sendiri, menulis changelog manual, lalu membuat tag Git tanpa aturan yang jelas—risiko salah rilis akan terus berulang. Masalah umum biasanya sederhana: commit tidak konsisten, changelog tidak lengkap, versi loncat, atau tag rilis tidak sesuai isi perubahan.

Solusi yang cukup stabil adalah membangun release flow otomatis dengan Conventional Commits. Dengan pendekatan ini, pesan commit menjadi sumber kebenaran untuk validasi perubahan, pembuatan changelog, penentuan versi berikutnya, sampai pembuatan tag rilis. Artikel ini fokus pada implementasi praktis untuk proyek CodeIgniter 4, terutama untuk tim kecil-menengah yang ingin developer experience lebih rapi tanpa proses yang terlalu berat.

Mengapa release flow otomatis relevan untuk proyek CodeIgniter 4?

CodeIgniter 4 sendiri tidak memaksa pola release tertentu. Itu memberi fleksibilitas, tetapi juga berarti setiap tim harus mendesain proses rilisnya sendiri. Pada aplikasi web internal, API backend, atau monolit CI4 yang dikerjakan beberapa developer, masalah berikut sering muncul:

  • Commit message tidak konsisten, sehingga sulit membaca riwayat perubahan.
  • Changelog tertinggal karena ditulis belakangan atau lupa diperbarui.
  • Version bump manual rawan salah, misalnya perubahan breaking justru dirilis sebagai patch.
  • Tag rilis tidak disiplin, sehingga deployment sulit ditelusuri ke commit tertentu.
  • Review PR tidak cukup menjaga kualitas commit jika tidak ada validasi otomatis.

Release flow otomatis membantu karena aturan dipindahkan dari kebiasaan manusia ke tooling. Hasilnya biasanya:

  • Rilis lebih mudah diaudit.
  • Commit history lebih mudah dibaca.
  • Changelog lebih konsisten untuk QA, PM, dan developer.
  • Proses rilis bisa dijalankan dari CI, bukan laptop salah satu anggota tim.

Gambaran arsitektur alur rilis

Alur sederhananya bisa dibuat seperti ini:

  1. Developer membuat commit mengikuti format Conventional Commits.
  2. Git hook lokal memvalidasi format commit sebelum commit diterima.
  3. Pull request atau merge request diverifikasi ulang di CI agar aturan tidak bisa dilewati.
  4. Saat perubahan masuk ke branch rilis utama, pipeline menentukan apakah ada release baru.
  5. Tool release membuat version bump, CHANGELOG, dan Git tag.
  6. CI membangun artefak rilis, misalnya file ZIP aplikasi atau image container.

Untuk implementasi praktis, kombinasi yang umum dan cukup ringan adalah:

  • commitlint untuk validasi format commit message.
  • Husky untuk menjalankan validasi di lokal melalui Git hooks.
  • semantic-release atau pendekatan sejenis untuk otomatisasi release.

Catatan: CodeIgniter 4 adalah framework PHP, tetapi tooling validasi commit dan release sering berjalan di ekosistem Node.js. Ini normal. Banyak tim PHP menggunakan Node hanya untuk automation layer seperti lint commit, changelog, dan release management.

Struktur Conventional Commits yang disarankan

Format dasar Conventional Commits:

<type>(<scope>): <subject>

Contoh yang relevan untuk aplikasi CodeIgniter 4:

feat(auth): tambah endpoint refresh token
fix(invoice): perbaiki validasi total pajak
refactor(user): rapikan service sinkronisasi profil
docs(readme): perbarui panduan setup lokal
test(api): tambah test untuk endpoint login
chore(ci): update workflow release

Tipe commit yang paling berguna

  • feat: fitur baru, biasanya memicu minor release.
  • fix: perbaikan bug, biasanya memicu patch release.
  • refactor: perubahan struktur kode tanpa mengubah perilaku eksternal.
  • docs: perubahan dokumentasi.
  • test: penambahan atau perbaikan test.
  • chore: pekerjaan rutin seperti update CI, tooling, atau dependency non-fungsional.
  • perf: optimasi performa.
  • build: perubahan terkait build system atau packaging.
  • ci: perubahan pipeline CI/CD.

Menandai breaking change

Untuk perubahan yang tidak kompatibel ke belakang, gunakan salah satu dari dua bentuk berikut:

feat(api)!: ubah format response detail invoice

atau tambahkan footer:

feat(api): ubah format response detail invoice

BREAKING CHANGE: field total_amount diganti menjadi grand_total

Ini penting karena tooling release dapat membaca breaking change untuk menaikkan versi mayor secara otomatis.

Saran scope untuk proyek CI4

Gunakan scope yang dekat dengan struktur domain aplikasi, bukan nama developer atau nama tugas sprint. Contoh scope yang cukup jelas:

  • auth
  • user
  • invoice
  • api
  • admin
  • billing
  • ci
  • deploy

Kalau tim terlalu banyak variasi scope, history jadi sulit dibaca. Lebih baik punya daftar scope yang disepakati daripada membebaskan semuanya.

Implementasi bertahap di proyek CodeIgniter 4

1. Tambahkan tooling commitlint dan Husky

Di root proyek CI4, tambahkan dependency development untuk automation layer. Contohnya:

npm install --save-dev @commitlint/cli @commitlint/config-conventional husky

Buat konfigurasi commitlint.config.js:

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      ['feat', 'fix', 'docs', 'refactor', 'test', 'chore', 'perf', 'build', 'ci']
    ],
    'scope-case': [2, 'always', 'kebab-case'],
    'subject-empty': [2, 'never']
  }
};

Inisialisasi Husky lalu tambahkan hook commit-msg:

npx husky init
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit "$1"'

Dengan hook ini, commit seperti berikut akan ditolak:

update login

Sedangkan ini akan lolos:

fix(auth): perbaiki redirect setelah login gagal

2. Tambahkan script yang konsisten untuk tim

Simpan perintah yang sering dipakai di package.json agar tidak tergantung hafalan tiap developer.

{
  "scripts": {
    "commitlint": "commitlint --from=HEAD~1 --to=HEAD",
    "release": "semantic-release"
  }
}

Walau proyek utamanya PHP, file package.json tetap berguna sebagai entry point tooling tim.

3. Pilih strategi versioning

Untuk mayoritas aplikasi CodeIgniter 4, gunakan Semantic Versioning:

  • MAJOR: breaking change.
  • MINOR: fitur baru yang kompatibel.
  • PATCH: bug fix atau perubahan kecil kompatibel.

Contoh interpretasi commit:

  • fix(auth): ... -> patch
  • feat(report): ... -> minor
  • feat(api)!: ... -> major

Jika aplikasi Anda bukan produk publik dan tidak mengekspos API stabil ke pihak lain, versi mayor mungkin jarang berubah. Tetap simpan aturan ini agar perubahan breaking terdeteksi dengan jelas, terutama jika ada integrasi mobile app, partner system, atau frontend terpisah.

4. Otomatiskan changelog, tag, dan release

Untuk tahap ini, tim biasanya memilih semantic-release karena ia dapat membaca commit, menentukan versi, membuat tag, dan memperbarui catatan rilis. Paket yang sering dipakai:

npm install --save-dev semantic-release @semantic-release/commit-analyzer @semantic-release/release-notes-generator @semantic-release/changelog @semantic-release/git

Contoh konfigurasi sederhana di .releaserc.json:

{
  "branches": ["main"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    [
      "@semantic-release/changelog",
      {
        "changelogFile": "CHANGELOG.md"
      }
    ],
    [
      "@semantic-release/git",
      {
        "assets": ["CHANGELOG.md"],
        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
      }
    ]
  ]
}

Konfigurasi ini cukup untuk memulai, tetapi ada satu hal penting: beberapa tim tidak ingin file versi diubah di repository, sementara tim lain ingin menyimpan informasi versi untuk ditampilkan di aplikasi. Keduanya valid.

5. Menyimpan versi rilis di aplikasi CI4

Jika aplikasi Anda perlu menampilkan versi build di halaman admin atau endpoint health check, buat file sederhana seperti app/Config/AppVersion.php atau file metadata lain yang di-update saat release.

Contoh file:

<?php

namespace Config;

class AppVersion
{
    public const VERSION = '1.4.2';
}

Lalu tampilkan di controller atau view internal:

<?php

namespace App\Controllers;

use Config\AppVersion;

class Health extends BaseController
{
    public function index()
    {
        return $this->response->setJSON([
            'status' => 'ok',
            'version' => AppVersion::VERSION,
        ]);
    }
}

Secara praktik, update file ini bisa dilakukan oleh script release tambahan. Namun jika tim ingin meminimalkan kompleksitas awal, cukup gunakan Git tag sebagai sumber versi dan jangan ubah file aplikasi dulu.

Alur branch dan merge yang sederhana

Untuk tim kecil-menengah, jangan mulai dengan strategi branch yang terlalu rumit. Pola berikut biasanya cukup:

  • main: branch yang selalu siap dirilis.
  • feature/*: branch kerja harian.
  • hotfix/*: perbaikan cepat untuk produksi jika diperlukan.

Alurnya:

  1. Developer membuat branch fitur dari main.
  2. Setiap commit wajib mengikuti Conventional Commits.
  3. Buka pull request ke main.
  4. CI memverifikasi test, coding standard, dan commit message.
  5. Setelah merge ke main, pipeline release berjalan.

Pendekatan ini sengaja sederhana agar tim tidak sibuk mengelola branch release terpisah. Jika nanti kebutuhan meningkat—misalnya ada beberapa environment, freeze period, atau multiple supported versions—barulah pertimbangkan branch release khusus.

Merge commit, squash, atau rebase?

Jika tujuan utama Anda adalah commit history yang rapi dan dapat dipakai untuk release otomatis, squash merge sering menjadi pilihan paling aman. Alasannya:

  • Satu pull request menghasilkan satu commit utama yang mudah dikontrol.
  • Reviewer bisa memastikan pesan akhir sesuai Conventional Commits.
  • Riwayat branch fitur yang berisik tidak ikut masuk ke main.

Konsekuensinya, developer perlu disiplin mengisi judul squash commit dengan format yang benar. Jika platform Git Anda mendukung aturan merge message, manfaatkan itu.

Validasi di CI: jangan hanya mengandalkan hook lokal

Husky membantu di mesin developer, tetapi tidak cukup. Hook lokal bisa dilewati, misalnya saat commit dibuat dari tool tertentu, atau saat hook belum terpasang. Karena itu, CI harus menjadi lapisan verifikasi kedua.

Contoh tanggung jawab pipeline CI untuk proyek CodeIgniter 4:

  • Install dependency PHP dan tooling Node untuk release automation.
  • Jalankan validasi commit message pada commit di pull request.
  • Jalankan test aplikasi CI4.
  • Jika branch adalah main dan semua lolos, jalankan proses release.
  • Buat artefak rilis seperti ZIP source siap deploy atau image container.

Contoh langkah CI secara umum

1. Checkout repository
2. Setup PHP
3. Install composer dependencies
4. Setup Node.js
5. Install npm dependencies
6. Validate commit messages
7. Run tests
8. If branch == main: run semantic-release
9. Build release artifact
10. Publish artifact or attach to release

Artikel ini sengaja tidak mengunci ke satu platform CI tertentu, karena GitHub Actions, GitLab CI, dan platform lain punya sintaks berbeda. Yang lebih penting adalah pembagian tahapnya, bukan nama field YAML-nya.

Apa yang diverifikasi di tahap commit?

Validasi commit di CI bisa dilakukan terhadap:

  • Commit terakhir pada push.
  • Seluruh commit dalam pull request.
  • Commit hasil squash sebelum merge.

Untuk tim yang memakai squash merge, memvalidasi judul commit final sering lebih praktis daripada memaksa semua commit kerja harian sempurna. Namun jika Anda ingin disiplin penuh sejak awal, validasi semua commit tetap masuk akal.

Pembuatan artefak rilis untuk aplikasi CodeIgniter 4

Setelah versi dan tag dibuat, tahap berikutnya adalah membangun artefak yang bisa dipakai oleh deployment. Bentuk artefak tergantung cara Anda deploy:

  • ZIP/TAR source package untuk shared hosting atau server tradisional.
  • Docker image untuk deployment berbasis container.
  • Build package internal yang diteruskan ke sistem deployment lain.

Pada aplikasi CI4 yang dideploy sebagai source code, artefak ZIP biasanya berisi:

  • Folder aplikasi dan konfigurasi yang diperlukan.
  • Folder public.
  • Folder vendor jika dependency Composer ingin dibundel saat build.
  • File metadata release seperti CHANGELOG.md.

Pastikan Anda jelas memilih salah satu dari dua pendekatan berikut:

  1. Build artifact sudah lengkap, termasuk dependency produksi.
  2. Build artifact minimal, lalu dependency di-install di server target.

Pendekatan pertama lebih konsisten, tetapi artefaknya lebih besar. Pendekatan kedua lebih ringan, tetapi server deployment harus stabil dan punya toolchain yang sesuai.

Contoh kasus di aplikasi CodeIgniter 4

Misalkan Anda memiliki aplikasi CI4 untuk manajemen invoice. Dalam satu sprint ada perubahan berikut:

  • Tambah endpoint ekspor PDF invoice.
  • Perbaiki bug validasi nominal diskon.
  • Ubah format response API invoice agar frontend baru bisa membaca data lebih lengkap.

Commit yang benar bisa ditulis seperti ini:

feat(invoice): tambah endpoint ekspor pdf
fix(invoice): perbaiki validasi nominal diskon
feat(api)!: ubah format response detail invoice

BREAKING CHANGE: struktur response invoice kini memindahkan field items ke data.lines

Dampaknya pada release flow:

  • Tool membaca ada feat dan fix.
  • Ada breaking change, sehingga versi mayor naik.
  • Changelog otomatis menampilkan fitur, bug fix, dan catatan breaking change.
  • Tag rilis baru dibuat tanpa perlu developer menghitung versi manual.

Ini sangat membantu jika backend CI4 dipakai oleh frontend web, mobile app, atau integrasi eksternal. Tim konsumen API langsung tahu bahwa ada perubahan inkompatibel.

Jebakan umum dan cara menghindarinya

1. Scope terlalu bebas

Jika setiap orang menulis scope sesuka hati, hasil changelog akan berantakan. Solusinya, definisikan daftar scope yang disepakati tim.

2. Commit lint hanya aktif di lokal

Ini kesalahan paling sering. Saat hook lokal tidak terpasang, aturan bisa bocor. Solusinya, validasi harus dijalankan lagi di CI.

3. Semua perubahan dimasukkan sebagai feat

Kalau bug fix ditulis sebagai feat, versi minor akan terlalu sering naik dan changelog menjadi menyesatkan. Edukasi tim bahwa type commit memengaruhi versi, bukan sekadar label kosmetik.

4. Squash merge menghasilkan pesan commit yang salah

Banyak tim sudah rapi di branch fitur, tetapi saat squash merge, judul final menjadi seperti Merge pull request #123 atau update branch. Solusinya, wajibkan penulisan pesan squash commit sesuai format Conventional Commits.

5. Breaking change tidak ditandai

Perubahan API yang merusak kompatibilitas sering lolos sebagai feat biasa. Akibatnya, konsumen API kaget saat deploy. Biasakan memakai tanda ! atau footer BREAKING CHANGE:.

6. File changelog sering konflik

Jika changelog diubah manual di banyak branch, konflik merge mudah terjadi. Solusinya, biarkan changelog utama dihasilkan saat proses release pada branch utama, bukan diedit di setiap branch fitur.

7. Release dijalankan dari laptop developer

Meskipun tool-nya otomatis, jika tetap dijalankan manual dari laptop, Anda masih bergantung pada environment personal. Praktik yang lebih aman adalah menjalankan release dari CI dengan token repository yang terkontrol.

Tips debugging saat release otomatis gagal

  • Commit tidak terdeteksi untuk release: periksa apakah type commit termasuk yang dianalisis tool release.
  • Tidak ada versi baru: bisa jadi semua commit hanya docs, chore, atau tipe lain yang tidak memicu release.
  • Tag gagal dibuat: periksa permission token CI ke repository.
  • Changelog kosong atau aneh: audit format commit pada merge terakhir.
  • Hook Husky tidak jalan: pastikan dependency ter-install dan folder hook benar-benar ada di repository.
  • Release berulang pada commit yang sama: cek apakah tag berhasil dipush dan terbaca oleh pipeline berikutnya.

Jangan langsung menyalahkan tool. Sebagian besar masalah release otomatis justru berasal dari aturan commit yang tidak konsisten atau alur merge yang tidak jelas.

Checklist adopsi untuk tim kecil-menengah

  1. Tentukan branch utama rilis, biasanya main.
  2. Sepakati daftar type dan scope commit.
  3. Tambahkan commitlint dan Husky di root proyek CI4.
  4. Buat dokumentasi singkat: contoh commit benar dan salah.
  5. Aktifkan validasi commit di CI, bukan hanya lokal.
  6. Pilih strategi merge, idealnya squash merge bila ingin riwayat ringkas.
  7. Tambahkan automation untuk changelog, version bump, dan tag release.
  8. Tentukan format artefak rilis: ZIP, Docker image, atau lainnya.
  9. Pastikan token CI punya izin yang cukup untuk membuat tag/release.
  10. Uji alur di repository percobaan sebelum diterapkan ke proyek produksi.
  11. Tinjau ulang aturan setelah 2-3 sprint; jangan terlalu kaku jika scope atau type perlu disesuaikan.

Kapan pendekatan ini cocok, dan kapan perlu disederhanakan?

Pendekatan ini cocok jika:

  • Ada lebih dari satu developer aktif.
  • Rilis terjadi berkala, bukan sangat jarang.
  • Perubahan perlu bisa dilacak ke versi dan tag tertentu.
  • Aplikasi CI4 memiliki API atau modul yang berdampak ke tim lain.

Mungkin terlalu berat jika:

  • Proyek sangat kecil dan hampir tidak pernah dirilis formal.
  • Hanya satu developer dengan alur deployment sederhana dan tanpa kebutuhan audit.

Namun bahkan pada tim kecil, minimal adopsi Conventional Commits + commitlint + validasi CI sudah memberi manfaat besar. Anda belum harus mengotomatiskan semua hal sekaligus.

Penutup

CodeIgniter 4: release flow otomatis dengan Conventional Commits bukan sekadar soal gaya menulis commit. Nilai utamanya ada pada konsistensi proses: perubahan tervalidasi, changelog dihasilkan dari riwayat nyata, versi ditentukan otomatis, dan tag rilis dibuat tanpa langkah manual yang mudah salah.

Untuk implementasi yang aman, mulai dari yang kecil: validasi commit message dulu, lalu tambahkan changelog dan tag release di CI. Setelah tim nyaman, baru perluas ke version file aplikasi, artefak rilis, atau deployment otomatis. Pendekatan bertahap seperti ini biasanya lebih berhasil daripada mencoba merombak seluruh proses rilis dalam satu hari.