Belajar GitHub Actions - Dynamic Matrix Testing (Matrix Strategy)

#Pendahuluan

Di episode 6 kita belajar mengontrol alur job dengan needs dan if. Sekarang bayangkan sebuah aplikasi yang harus berjalan di Windows, macOS, dan Linux, sekaligus mendukung Node.js 18, 20, dan 22. Berapa banyak definisi job yang harus kalian tulis? Naif kalau menyalin-tempel definisi job yang sama sampai sembilan kali — selain boros, setiap duplikasi adalah calon sumber bug karena satu salinan lupa diperbarui.

GitHub Actions punya jawaban elegan untuk masalah ini: matrix strategy. Dengan satu definisi job, kalian bisa menguji aplikasi pada banyak kombinasi sistem operasi dan versi bahasa pemrograman sekaligus — dan setiap kombinasi berjalan sebagai job terpisah secara paralel. Di episode ini kita akan membongkar cara kerjanya beserta seluruh kustomisasinya.

#Pembahasan Utama

#Konsep Matrix Strategy

Matrix strategy seperti uji kualitas produk di berbagai kondisi sebelum dirilis: apakah sepatu ini masih nyaman di jalan licin? Di cuaca panas? Di medan berbatu? Satu produk, banyak skenario. Di GitHub Actions, skenario-skenario itu adalah kombinasi nilai yang kalian definisikan, dan masing-masing kombinasi dijalankan sebagai job runner yang independen.

Dengan matrix, kalian:

Satu definisi job untuk semua kombinasi — tanpa duplikasi kode.
Paralel penuh — semua kombinasi dijalankan bersamaan, total waktu pipeline tidak bertambah.
Hasil terpisah — setiap kombinasi punya log dan status check-nya sendiri.

#Konfigurasi Dasar strategy.matrix

Cara pakainya: di bawah strategy pada level job, definisikan matrix dengan satu atau lebih array nilai. GitHub lalu membuat produk kartesian dari semua array tersebut:

Definisi matrix dasar

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        node-version: [18, 20, 22]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm ci
      - run: npm test

Dengan tiga sistem operasi dan tiga versi Node.js, GitHub membuat 9 kombinasi — dan setiap kombinasi adalah job runner yang terpisah. Nilai kombinasi aktif dibaca lewat expression, misalnya matrix.os untuk memilih runner dan matrix.node-version untuk memilih versi Node. Kalian tinggal menulis logikanya sekali, GitHub yang memperbanyaknya.

Tip

Perhatikan bahwa expression matrix di atas memakai kurung kurawal ganda — hal itu normal di dalam file YAML workflow, dan memang hanya boleh muncul di dalam fenced code block seperti ini. Di UI, GitHub menampilkan setiap kombinasi sebagai run terpisah dengan label seperti "test (ubuntu-latest, 18)" sehingga mudah dibedakan.

#Membaca Nilai dari Matrix

Expression matrix mengikuti pola matrix.<key>. Key yang dipakai di ekspresi harus persis sama dengan key yang didefinisikan di matrix — salah ketik seperti matrix.node padahal yang ada matrix.node-version akan menghasilkan nilai kosong dan job langsung gagal. Inilah salah satu sumber error paling umum di pipeline matrix.

#include: Menambah Variasi Khusus

include menambahkan kombinasi yang tidak dihasilkan oleh produk kartesian. Ia juga bisa menambahkan key baru yang tidak ada di array utama, yang nantinya bisa dibaca sebagai matrix.<key> di dalam step:

Menambah variasi dengan include

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]
    node-version: [18, 20]
    include:
      - os: macos-latest
        node-version: 22
        coverage: true

Di sini kombinasi dasar hanya 2 dikali 2, lalu include menambahkan satu job di macOS dengan Node.js 22. Key ekstra coverage bisa dipakai di step, misalnya untuk menjalankan laporan coverage hanya pada satu kombinasi saja.

#exclude: Membuang Kombinasi Tertentu

exclude adalah kebalikannya — menghapus kombinasi yang tidak kalian inginkan. Cocok untuk menyingkirkan kombinasi yang tidak didukung vendor atau terlalu lama diuji:

Membuang kombinasi dengan exclude

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest, macos-latest]
    node-version: [18, 20, 22]
    exclude:
      - os: windows-latest
        node-version: 18

Kombinasi "Windows + Node 18" (jika memang tidak didukung aplikasi) langsung dibuang dari daftar run. Catatan penting: nilai di exclude harus cocok persis dengan kombinasi yang benar-benar dihasilkan matrix — jika tidak cocok, ia diabaikan tanpa efek.

#max-parallel dan fail-fast

Dua pengatur perilaku eksekusi matrix:

max-parallel membatasi jumlah kombinasi yang berjalan bersamaan — berguna saat kuota menit runner terbatas atau aplikasi kalian butuh sumber daya yang tidak boleh dihabiskan semua sekaligus.
fail-fast mengontrol perilaku ketika satu kombinasi gagal. Defaultnya true: kombinasi lain langsung dibatalkan begitu ada satu yang gagal. Set ke false jika kalian ingin semua kombinasi tetap jalan sampai selesai, misalnya untuk melihat laporan kegagalan lengkap.

Kontrol paralel dan kegagalan

strategy:
  fail-fast: false
  max-parallel: 2
  matrix:
    os: [ubuntu-latest, windows-latest, macos-latest]
    node-version: [18, 20, 22]

Dengan max-parallel: 2, dari 9 kombinasi hanya 2 yang berjalan bersamaan, sisanya mengantre. Ini pola favorit tim yang bekerja di jam sibuk dan tidak mau kuota menitnya habis seketika.

#Workflow Lengkap Matrix Test

Mari satukan semuanya dalam workflow yang siap dipakai tim:

Workflow matrix lengkap

name: Matrix Test
on:
  push:
  pull_request:
jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      max-parallel: 2
      matrix:
        os: [ubuntu-latest, windows-latest]
        node-version: [18, 20, 22]
        include:
          - os: macos-latest
            node-version: 22
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm ci
      - run: npm test

Workflow ini menghasilkan 7 run: 2 OS dikali 3 versi Node (6 kombinasi) ditambah 1 kombinasi macOS dari include. fail-fast: false memastikan satu kegagalan tidak membatalkan pengujian di sistem operasi lain — informasi yang berharga saat menelusuri bug yang hanya muncul di platform tertentu.

Warning

Hati-hati dengan ledakan kombinasi. Menguji 3 OS dikali 3 versi Node dikali 2 versi dependency dikali 2 skema database = 36 job, dan semuanya berjalan paralel pada awalnya. Kalau kuota menit kalian terbatas, kombinasi sebanyak itu bisa menghabiskan jatah dalam sekali push. Kombinasikan max-parallel, exclude, dan sesuaikan jumlah variasi — uji silang penuh cukup di CI utama, sementara PR biasa cukup pada satu matrix yang ramping.

#Kesalahan Umum

Kesalahan	Gejala	Solusi
Salah ketik nama key matrix	Nilai ekspresi kosong, job gagal	Samakan persis key di ekspresi dengan definisi
`exclude` tidak cocok kombinasi	Kombinasi tetap dijalankan	Pastikan nilai identik dengan hasil kartesian
`fail-fast` dibiarkan `true`	Kombinasi lain dibatalkan saat satu gagal	Set `false` bila ingin laporan lengkap
Terlalu banyak kombinasi	Kuota menit cepat habis	Pakai `max-parallel`, `exclude`, matrix ramping
Matrix tanpa `include` untuk kasus khusus	Job khusus ditulis terpisah, boros	Manfaatkan `include` + key ekstra

#Penutup

Matrix strategy adalah senjata utama untuk pengujian multiplatform:

Satu definisi, banyak kombinasi — produk kartesian array di matrix menghasilkan job terpisah per kombinasi.
include menambah variasi khusus dan key ekstra; exclude membuang kombinasi yang tak diinginkan.
max-parallel mengendalikan beban, fail-fast mengontrol nasib kombinasi lain saat satu gagal.
Nama key harus konsisten antara definisi dan ekspresi matrix.<key>.

Di episode 8 selanjutnya, kita akan membahas Manajemen Artifacts & Caching — cara memindahkan hasil build antar job dengan artifacts dan mempercepat pipeline dengan cache dependensi. Dua kemampuan ini yang membuat workflow multi-job kalian terasa ringan dan cepat!