Memakai Guard Clause untuk CI Script dan CLI yang Mudah Dirawat

Guard clause adalah pola menaruh pengecekan kondisi penting di awal lalu keluar segera jika syarat tidak terpenuhi. Untuk CI script, CLI internal, dan pipeline deployment, pola ini sangat berguna karena membuat kegagalan terjadi lebih cepat, pesan error lebih jelas, dan logika tidak tenggelam dalam if/else bersarang.

Dalam praktiknya, memakai guard clause untuk CI script dan CLI yang mudah dirawat berarti memindahkan validasi precondition ke bagian atas: apakah environment variable wajib tersedia, apakah branch yang berjalan benar, apakah tag release valid, apakah lock file ada, dan apakah command sebelumnya sukses. Hasilnya bukan hanya kode lebih rapi, tetapi juga pipeline yang lebih mudah di-debug saat gagal.

Apa itu guard clause dalam konteks otomasi

Konsep guard clause sering dipahami sebagai: tolak input atau keadaan yang tidak valid sedini mungkin, lalu biarkan alur utama tetap lurus. Ide ini mirip dengan guard dalam bahasa yang mendukung validasi kondisi secara deklaratif, tetapi di shell script, Node.js, atau GitHub Actions kita menerapkannya dengan exit, return, atau if singkat di awal langkah.

Tujuannya bukan sekadar mempersingkat kode. Guard clause membantu memisahkan dua hal:

Precondition: syarat yang wajib benar sebelum kerja utama dimulai.
Main path: alur sukses yang ingin kita baca tanpa gangguan cabang bersarang.

Pemisahan ini penting pada script otomasi karena banyak kegagalan sebenarnya bukan bug logika utama, melainkan keadaan awal yang salah: token belum diset, branch tidak sesuai, workspace kotor, atau artefak lama belum dibersihkan.

Mengapa guard clause cocok untuk CI script dan CLI

1. Gagal lebih cepat dan lebih murah

Pipeline CI/CD biasanya menjalankan langkah yang mahal: install dependency, build image, test integration, upload artefak, atau deploy. Jika branch salah atau credential belum tersedia, lebih baik pipeline berhenti pada detik awal daripada setelah 10 menit komputasi.

2. Log lebih mudah dipahami

Pesan seperti ERROR: DEPLOY_ENV belum diset jauh lebih berguna daripada stack trace umum atau kegagalan command lanjutan yang efeknya tidak langsung menjelaskan akar masalah.

3. Mengurangi branching bersarang

Tanpa guard clause, script otomasi sering menjadi rangkaian if ... then ... else yang makin dalam. Ini menyulitkan review PR karena reviewer harus melacak syarat dari luar ke dalam. Dengan guard clause, kasus gagal dikeluarkan di awal, dan jalur sukses tetap datar.

4. Memaksa kontrak eksekusi lebih jelas

CLI internal dan script release idealnya punya kontrak yang eksplisit: input apa yang wajib, siapa yang boleh menjalankan, dari branch mana, dan di lingkungan apa. Guard clause membuat kontrak ini nyata dalam kode, bukan hanya di dokumentasi.

Contoh sebelum dan sesudah di shell script

Sebelum: if bersarang dan pesan gagal tidak fokus

#!/usr/bin/env bash

if [ -n "$GITHUB_REF" ]; then
  if [ -n "$DEPLOY_ENV" ]; then
    if [ "$GITHUB_REF" = "refs/heads/main" ]; then
      if [ -f "package-lock.json" ]; then
        npm ci
        npm run build
        npm run deploy -- --env "$DEPLOY_ENV"
      else
        echo "lock file tidak ditemukan"
      fi
    else
      echo "branch bukan main"
    fi
  else
    echo "DEPLOY_ENV kosong"
  fi
else
  echo "GITHUB_REF kosong"
fi

Script di atas masih bisa jalan, tetapi ada beberapa masalah:

Alur sukses tersembunyi di level terdalam.
Setiap kondisi gagal dibungkus ke dalam kondisi lain.
Tidak ada exit code yang jelas.
Jika satu command gagal, perilakunya tergantung shell dan pengaturan script.

Sesudah: guard clause di awal

#!/usr/bin/env bash
set -euo pipefail

fail() {
  echo "ERROR: $*" >&2
  exit 1
}

[ -n "${GITHUB_REF:-}" ] || fail "GITHUB_REF belum diset"
[ -n "${DEPLOY_ENV:-}" ] || fail "DEPLOY_ENV belum diset"
[ "$GITHUB_REF" = "refs/heads/main" ] || fail "deploy hanya boleh dari branch main"
[ -f "package-lock.json" ] || fail "package-lock.json tidak ditemukan"

npm ci
npm run build
npm run deploy -- --env "$DEPLOY_ENV"

Versi ini lebih mudah dibaca karena semua precondition dikumpulkan di awal, lalu alur utama tinggal tiga baris. Pola ini juga lebih aman karena:

set -e menghentikan script saat command gagal.
set -u menganggap variabel yang belum diset sebagai error.
pipefail membantu mendeteksi kegagalan dalam pipeline command.

Catatan: set -e berguna, tetapi jangan menganggapnya pengganti guard clause. set -e bereaksi pada kegagalan command, sedangkan guard clause menjelaskan mengapa script tidak boleh lanjut sebelum command utama dijalankan.

Validasi yang paling sering layak dijadikan guard clause

Environment variable wajib

Ini penggunaan paling umum. Script release dan deploy hampir selalu membutuhkan token, nama environment, region, atau endpoint tertentu.

required_vars=(DEPLOY_ENV API_TOKEN REGISTRY_URL)

for name in "${required_vars[@]}"; do
  [ -n "${!name:-}" ] || fail "$name belum diset"
done

Pola ini lebih baik daripada membiarkan command di bawah gagal dengan pesan yang tidak relevan, misalnya 401 dari API padahal masalahnya token kosong.

Pengecekan branch atau tag

Banyak pipeline hanya boleh jalan pada branch atau tag tertentu. Jadikan itu precondition eksplisit.

case "${GITHUB_REF:-}" in
  refs/heads/main|refs/heads/release/*) ;;
  refs/tags/v*) ;;
  *) fail "pipeline ini hanya boleh dijalankan dari main, release/*, atau tag v*" ;;
esac

Gunakan guard clause untuk mencegah deploy tidak sengaja dari branch feature. Untuk release berbasis tag, validasi format tag juga membantu menghindari artefak yang salah nama.

File lock atau lock file dependency

Istilah lock file di sini bisa berarti dua hal, dan keduanya relevan:

Dependency lock file seperti package-lock.json, pnpm-lock.yaml, atau yarn.lock.
Runtime lock file untuk mencegah dua proses berjalan bersamaan.

Untuk dependency lock file, guard clause memastikan build benar-benar reproducible:

[ -f "package-lock.json" ] || fail "package-lock.json wajib ada untuk build yang konsisten"

Untuk runtime lock file, guard clause mencegah eksekusi paralel yang saling menimpa:

LOCK_FILE="/tmp/my-deploy.lock"

[ ! -e "$LOCK_FILE" ] || fail "deploy lain sedang berjalan: $LOCK_FILE"
trap 'rm -f "$LOCK_FILE"' EXIT
: > "$LOCK_FILE"

Pendekatan file lock sederhana ini cukup untuk banyak script internal, tetapi punya keterbatasan pada sistem paralel atau mesin yang berbeda. Jika workflow berjalan di beberapa runner atau host, gunakan mekanisme lock yang memang terkoordinasi di tingkat CI platform, storage bersama, atau service eksternal.

Cek tool atau command yang wajib ada

command -v jq >/dev/null 2>&1 || fail "jq tidak terpasang"
command -v docker >/dev/null 2>&1 || fail "docker tidak terpasang"

Ini penting untuk script yang dijalankan lokal oleh tim, karena asumsi lingkungan developer sering berbeda-beda.

Guard clause pada CLI internal dengan Node.js

Untuk CLI berbasis Node.js, guard clause biasanya berbentuk validasi argumen dan environment sebelum proses utama dimulai. Fokusnya sama: keluarkan kasus gagal dari awal agar fungsi utama tidak dipenuhi percabangan defensif.

Sebelum: logika utama tercampur validasi

#!/usr/bin/env node

async function main() {
  const env = process.argv[2];

  if (env) {
    if (process.env.API_TOKEN) {
      if (["staging", "production"].includes(env)) {
        console.log(`Deploy ke ${env}...`);
        // proses deploy
      } else {
        console.error("Environment tidak valid");
        process.exit(1);
      }
    } else {
      console.error("API_TOKEN belum diset");
      process.exit(1);
    }
  } else {
    console.error("Argumen environment wajib diisi");
    process.exit(1);
  }
}

main();

Sesudah: precondition dipisah, main path lebih jelas

#!/usr/bin/env node

function fail(message, code = 1) {
  console.error(`ERROR: ${message}`);
  process.exit(code);
}

function getDeployEnv(argv) {
  const env = argv[2];
  env || fail("Argumen environment wajib diisi, contoh: deploy staging");
  ["staging", "production"].includes(env) || fail(`Environment tidak valid: ${env}`);
  return env;
}

function requireEnv(name) {
  const value = process.env[name];
  value || fail(`${name} belum diset`);
  return value;
}

async function main() {
  const env = getDeployEnv(process.argv);
  const token = requireEnv("API_TOKEN");

  console.log(`Deploy ke ${env}...`);
  void token;
  // proses deploy
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

Keuntungan pendekatan ini:

Validasi dapat diuji terpisah.
Fungsi utama fokus pada pekerjaan utama.
Pesan error konsisten.
Lebih mudah ditambah guard baru tanpa menambah nesting.

Kapan memakai exit code yang berbeda

Sering kali cukup menggunakan exit 1. Namun pada CLI yang dipakai oleh script lain, exit code yang berbeda bisa membantu otomatisasi mengambil keputusan:

0: sukses.
1: error umum.
2: input/argumen tidak valid.
3: precondition lingkungan tidak terpenuhi.

Tidak ada satu standar universal untuk semua CLI internal. Yang penting adalah konsisten dan terdokumentasi agar pipeline di atasnya tahu bagaimana menafsirkan kegagalan.

Guard clause di GitHub Actions

GitHub Actions sudah punya fitur seperti if: pada job dan step, tetapi guard clause tetap relevan. Bedanya, Anda bisa menaruh guard di dua level:

Level workflow/job untuk mencegah job berjalan sama sekali.
Level script step untuk memvalidasi kondisi yang lebih detail dan memberi pesan error yang lebih spesifik.

Contoh level job

jobs:
  deploy:
    if: startsWith(github.ref, 'refs/tags/v')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy release
        run: ./scripts/deploy.sh

Ini efisien karena job deploy tidak dibuat saat ref bukan tag release.

Contoh level script step dengan guard clause

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validasi precondition
        env:
          DEPLOY_ENV: production
          API_TOKEN: ${{ secrets.API_TOKEN }}
        run: |
          set -euo pipefail

          fail() {
            echo "ERROR: $*" >&2
            exit 1
          }

          [ -n "${API_TOKEN:-}" ] || fail "secret API_TOKEN belum tersedia"
          [ "${GITHUB_REF}" = "refs/heads/main" ] || fail "deploy manual hanya boleh dari main"
          [ -f "package-lock.json" ] || fail "package-lock.json tidak ditemukan"

      - name: Build
        run: npm ci && npm run build

      - name: Deploy
        env:
          API_TOKEN: ${{ secrets.API_TOKEN }}
        run: ./scripts/deploy.sh

Kelebihan pola ini adalah pesan kegagalan menjadi lebih eksplisit daripada hanya mengandalkan kondisi tersebar di banyak step. Namun, jangan memindahkan semua logika ke dalam YAML. Untuk validasi yang kompleks atau dipakai berulang, lebih baik ekstrak ke script terpisah agar bisa diuji dan dipakai linting.

Exit code, fail-fast, dan debugging

Bedakan kegagalan validasi dengan kegagalan proses

Guard clause biasanya menangani kegagalan validasi awal. Setelah lolos validasi, kegagalan berikutnya biasanya berasal dari proses utama: test gagal, API timeout, build rusak, dan sebagainya. Memisahkan dua jenis kegagalan ini memudahkan pembacaan log dan penentuan pemilik masalah.

Tulis pesan error yang operasional

Pesan guard clause sebaiknya menjawab dua hal:

Apa yang salah.
Apa yang diharapkan.

Contoh bagus:

fail "DEPLOY_ENV belum diset. Nilai yang diizinkan: staging atau production"

Contoh kurang membantu:

fail "invalid env"

Tambahkan konteks secukupnya

Untuk debugging, kadang berguna menampilkan nilai yang aman untuk dicetak, seperti branch aktif atau path file. Hindari mencetak secret atau token.

fail "branch saat ini ${GITHUB_REF:-unknown}, deploy hanya boleh dari refs/heads/main"

Jangan menelan exit code asli tanpa alasan

Jika sebuah command utama gagal, biarkan exit code-nya mengalir kecuali Anda memang ingin memetakannya ke kategori yang lebih spesifik. Membungkus semua kegagalan menjadi pesan generik justru menghilangkan informasi penting.

Kapan guard clause berlebihan

Guard clause bukan berarti setiap if harus dipindahkan ke awal. Ada beberapa batasan yang perlu dijaga.

1. Terlalu banyak guard membuat pembuka script penuh kebisingan

Jika bagian atas script berisi 20 pengecekan kecil tanpa struktur, pembaca tetap kesulitan memahami alurnya. Solusinya adalah mengelompokkan guard per kategori, misalnya validasi input, lingkungan, dan workspace.

2. Tidak semua percabangan adalah precondition

Jika percabangan memang bagian dari logika bisnis utama, jangan dipaksa menjadi guard clause. Contoh: strategi deploy berbeda untuk staging dan production. Itu bukan kondisi gagal, melainkan jalur kerja yang memang berbeda.

3. Guard yang duplikatif di banyak tempat

Bila validasi yang sama diulang di banyak script, ekstrak ke fungsi bersama atau wrapper script. Duplikasi guard membuat perubahan aturan lebih mudah terlewat.

4. Guard yang terlalu agresif bisa mengurangi fleksibilitas

Misalnya script dipaksa hanya jalan dari satu branch, padahal tim juga butuh mode percobaan untuk branch release tertentu. Guard clause harus mencerminkan kebijakan nyata, bukan mengunci use case yang valid.

Pola implementasi yang praktis

Buat helper fail dan helper require

Di shell script, dua helper sederhana sering cukup:

fail() {
  echo "ERROR: $*" >&2
  exit 1
}

require_env() {
  local name="$1"
  [ -n "${!name:-}" ] || fail "$name belum diset"
}

require_file() {
  local path="$1"
  [ -f "$path" ] || fail "file wajib tidak ditemukan: $path"
}

Dengan helper seperti ini, guard tetap singkat dan konsisten.

Pisahkan validasi ke fungsi tersendiri

validate_preconditions() {
  require_env DEPLOY_ENV
  require_env API_TOKEN
  require_file package-lock.json
  [ "$GITHUB_REF" = "refs/heads/main" ] || fail "deploy hanya boleh dari main"
}

main() {
  validate_preconditions
  npm ci
  npm run build
  npm run deploy -- --env "$DEPLOY_ENV"
}

main "$@"

Ini membantu jika script mulai tumbuh. Reviewer bisa membaca kontrak eksekusi pada satu fungsi, lalu membaca alur utama secara terpisah.

Letakkan guard sedekat mungkin dengan batas sistem

Untuk CLI, guard sebaiknya ada saat parsing input. Untuk pipeline, guard sebaiknya ada sebelum langkah mahal. Untuk script deploy, guard sebaiknya ada sebelum koneksi ke sistem luar dibuka. Semakin dekat ke pintu masuk, semakin kecil biaya kegagalan.

Refactor bertahap pada pipeline lama

Pipeline lama sering tumbuh organik: sedikit shell di YAML, sedikit command inline, sedikit copy-paste antar repository. Mengubah semuanya sekaligus berisiko. Refactor guard clause lebih aman bila dilakukan bertahap.

Identifikasi kegagalan yang paling sering terjadi. Mulai dari error yang berulang di log CI, misalnya secret kosong, branch salah, atau artefak tidak ada.
Pindahkan validasi itu ke awal. Tambahkan guard clause sebelum install/build/deploy.
Standarkan pesan error. Misalnya semua validasi awal memakai prefiks ERROR: dan format yang seragam.
Ekstrak inline script dari YAML. Jika validasi mulai panjang, pindahkan ke scripts/validate.sh atau CLI internal.
Hilangkan nesting satu per satu. Ubah if bersarang menjadi guard clause tanpa mengubah perilaku bisnis.
Tambahkan test ringan bila memungkinkan. Untuk Node.js, uji fungsi validasi. Untuk shell script, minimal uji kasus sukses dan gagal di CI lokal atau job terpisah.
Dokumentasikan kontrak eksekusi. Tulis environment variable wajib, branch yang diizinkan, serta exit code penting.

Pendekatan bertahap ini lebih realistis daripada menulis ulang pipeline dari nol. Fokusnya adalah mengurangi kompleksitas di titik yang paling sering menyulitkan operasi harian.

Checklist review PR untuk script automation

Gunakan daftar ini saat mereview perubahan pada script CI, CLI, atau deploy:

Apakah precondition penting divalidasi di awal dengan guard clause?
Apakah environment variable wajib dicek eksplisit?
Apakah branch, tag, atau event CI yang diizinkan sudah jelas?
Apakah file penting seperti lock file dependency diverifikasi sebelum build?
Apakah ada risiko eksekusi paralel yang butuh lock?
Apakah pesan error spesifik dan membantu tindakan perbaikan?
Apakah secret tidak pernah dicetak ke log?
Apakah alur sukses tetap datar dan mudah dibaca?
Apakah exit code konsisten dan masuk akal untuk caller di atasnya?
Apakah validasi yang sama sebaiknya diekstrak ke helper bersama?
Apakah ada guard clause yang sebenarnya bukan precondition, melainkan logika utama?
Apakah perubahan ini aman untuk workflow lama dan punya jalur migrasi yang jelas?

Kesalahan umum yang sering muncul

Mengandalkan kegagalan implisit

Contohnya membiarkan curl atau npm gagal sendiri tanpa menjelaskan bahwa token atau branch salah. Ini membuat diagnosis lebih lambat.

Menaruh guard terlalu jauh setelah langkah mahal

Jika validasi branch baru dicek setelah dependency di-install, manfaat fail-fast berkurang drastis.

Guard tersebar tanpa struktur

Validasi yang tersebar di lima fungsi berbeda sulit diaudit. Sebisa mungkin kumpulkan validasi awal pada satu tempat yang jelas.

Pesan error tidak menyebut ekspektasi

Pesan seperti invalid input memaksa pembaca membuka source code. Sebutkan nilai yang diharapkan atau cara memperbaikinya.

Penutup

Memakai guard clause untuk CI script dan CLI yang mudah dirawat adalah cara praktis untuk membuat otomasi lebih tegas terhadap precondition dan lebih ramah saat gagal. Dengan memvalidasi environment variable, branch/tag, lock file, serta kondisi eksekusi di awal, Anda menjaga alur utama tetap singkat dan mengurangi nesting yang tidak perlu.

Gunakan guard clause untuk kondisi yang memang harus benar sebelum proses dimulai. Jangan paksa semua percabangan menjadi guard. Jika diterapkan dengan disiplin, pola ini membuat pipeline lebih cepat gagal saat perlu, lebih mudah di-review, dan lebih sederhana dirawat dalam jangka panjang.

Quick Search

shopping_cart Keranjang