Belajar GitLab CI/CD - Troubleshooting, Debugging & Monitoring Pipeline

#Pendahuluan

Di episode 18 kita mengenal Auto DevOps dan komponen. Namun apa yang terjadi ketika pipeline yang tampak sempurna tiba-tiba gagal di tengah malam? Menatap log berwarna merah tanpa tahu harus mulai dari mana adalah momen yang akrab bagi semua engineer. Episode ini membahas senjata debugging GitLab — dari jejak shell yang sangat detail hingga terminal interaktif di dalam runner — lalu menutup dengan pemantauan kesehatan runner lewat Prometheus dan Grafana.

#Membaca Log Pipeline dengan Benar

Pertama, lawan refleks menyerahkan seluruh log ke tim lain. Setiap job yang gagal menyediakan informasi di tiga tempat: baris script yang gagal (biasanya ditandai di log), status exit code, dan artifact yang dihasilkan. Mulailah dari stage pertama yang gagal, bukan yang terakhir — kegagalan sering menular.

Penyebab gagal yang umum:

Gejala	Penyebab Umum
Exit code 1 di npm install	Versi lockfile tidak cocok
Job timeout	Perintah menunggu input interaktif
Image pull failed	Tag image salah atau registry privat
Command not found	Executor berbeda dari yang diharapkan
Cache tidak dipakai	Cache key berbeda antar job

#Debug Trace dengan CI_DEBUG_TRACE

Ketika error tidak jelas — misalnya variabel kosong padahal seharusnya terisi — aktifkan jejak shell. Variabel CI_DEBUG_TRACE membuat GitLab mencetak setiap perintah shell sebelum dieksekusi, lengkap dengan nilai variabelnya:

Aktifkan debug trace global

variables:
  CI_DEBUG_TRACE: "true"

Ini setara dengan menjalankan bash -x pada setiap script. Kalian akan melihat ekspansi variabel secara live — misalnya $CI_COMMIT_SHA berubah menjadi hash commit sesungguhnya — sehingga langsung terlihat apakah variabel kosong, salah ekspansi, atau mengandung spasi yang merusak perintah.

Warning

Debug trace memenuhi log dengan informasi sensitif: nilai variabel rahasia ikut tercetak. Jangan menyalakan CI_DEBUG_TRACE secara permanen, dan pastikan mematikannya sebelum pipeline produksi.

Cara yang lebih disarankan adalah menyalakan debug trace per run saja, lewat variabel pipeline di UI, tanpa mengubah file:

Menyalakan debug trace via UI

Pipeline -> Run pipeline -> Variables -> CI_DEBUG_TRACE = "true"

#Web Terminal untuk Debugging Interaktif

Kadang jejak statis tidak cukup — kita perlu mengetik perintah langsung di dalam lingkungan job yang gagal. GitLab menyediakan Web Terminal: begitu job sedang berjalan (atau dalam mode manual), kalian bisa membuka terminal interaktif dari halaman job di GitLab Premium.

Bekerja di dalam terminal itu seperti duduk di depan mesin yang sama: mencoba ls melihat struktur direktori, menjalankan ulang perintah yang gagal baris demi baris, dan mengamati environment variable yang benar-benar ada:

Menyelidiki lingkungan job

pwd
ls -la
printenv CI_PROJECT_DIR
printenv CI_JOB_TOKEN | head -c 8

Terminal ini hanya tersedia selama job berjalan dan memakai izin yang sama dengan job — jadi kalian bisa menguji perbaikan dalam kondisi yang persis sama dengan kegagalan aslinya, bukan menebak dari laptop.

#Memantau Kesehatan Runner

Debugging memperbaiki satu kegagalan; monitoring mencegah kegagalan berulang. GitLab Runner meng-export metriknya sendiri dalam format Prometheus, tinggal diaktifkan di config.toml:

config.toml - aktifkan metrics endpoint

[[runners]]
  name = "prod-runner"
  url = "https://gitlab.example.com"
  token = "xxxxxxxx"
 
  [runners.metrics]
    listen_address = ":9252"

Metrik yang bisa diambil antara lain gitlab_runner_jobs_total, gitlab_runner_job_duration_seconds, dan gitlab_runner_process_runner_version. Untuk memantaunya, arahkan Prometheus ke endpoint itu:

prometheus.yml - scrape metrics runner

scrape_configs:
  - job_name: gitlab-runner
    static_configs:
      - targets: ["runner01.example.com:9252"]

Tip

Metrik paling berguna untuk operasional: queue duration (berapa lama job menunggu runner kosong — jika naik, berarti kapasitas runner kurang) dan jumlah job gagal per interval. Dua metrik ini langsung menandakan kebutuhan scaling.

Grafana lalu menggambarkan metrik itu menjadi dashboard: CPU dan RAM runner, antrean job, serta rasio sukses-gagal. Dengan dashboard ini, masalah runner terlihat sebelum pengguna melapor — dan troubleshooting tidak lagi menunggu tengah malam.

Salah satu panel paling penting adalah queue duration: berapa lama job mengantre sebelum runner kosong. Di Prometheus, metrik ini adalah histogram:

Queue duration p95 di Prometheus

histogram_quantile(
  0.95,
  sum by (le) (rate(gitlab_runner_job_queue_duration_seconds_bucket[5m]))
)

Nilai yang konsisten di atas puluhan detik menandakan runner kekurangan kapasitas — saatnya menambah runner baru, bukan menyalahkan pipeline.

#Menjinakkan Job yang Gagal Berulang

Tidak semua kegagalan perlu ditangani manual. GitLab menyediakan retry untuk kegagalan yang bersifat sementara (runner crash, network hiccup) dan timeout agar job yang menggantung tidak menguras antrean selamanya:

retry dan timeout untuk job yang flaky

flaky_build:
  script:
    - npm ci
    - npm run build
  retry:
    max: 2
    when: runner_system_failure
  timeout: 30m

Jangan pernah memakai retry untuk menutupi kegagalan yang sistematis — jika npm ci gagal tiga kali berturut-turut, memperbanyak retry hanya menunda diagnosis. Gunakan retry untuk alasan yang jelas: runner_system_failure dan stuck_or_timeout_failure adalah kandidat paling aman.

#Penutup

Debug trace CI_DEBUG_TRACE mencetak seluruh jejak shell untuk menemukan ekspansi variabel yang salah.
Web Terminal memberi terminal interaktif di dalam runner untuk debugging kondisi nyata.
Metrik runner diaktifkan lewat listen_address di config.toml.
Prometheus meng-scrape metrik runner, Grafana menggambarkannya menjadi dashboard.
Queue duration dan job failure adalah dua sinyal scaling paling penting.

Di episode 20 — episode terakhir seri ini — kita menggabungkan semuanya: studi kasus pipeline production-grade lengkap dari commit pertama sampai alert ke tim. Sampai jumpa!