Deteksi secret bocor di CI dengan Gitleaks dan GitHub Actions adalah cara praktis untuk menghentikan token, API key, kredensial cloud, atau file konfigurasi sensitif sebelum perubahan digabung ke branch utama. Pendekatan ini tidak menghapus kebutuhan review manual, tetapi memberi guardrail otomatis agar kebocoran yang umum tidak lolos hanya karena kelalaian kecil.

Masalah yang paling sering terjadi bukan serangan yang rumit, melainkan file .env, credential sementara, private key, atau token uji yang ikut ter-commit. Dengan menempatkan pemindaian di pipeline CI, tim bisa mendapatkan umpan balik cepat pada pull request, menerapkan kebijakan gagal yang konsisten, dan mengurangi risiko secret tersimpan lama di riwayat repository.

Mengapa secret scanning perlu dijalankan di CI

Secret yang sudah masuk ke Git memiliki karakteristik yang merepotkan: ia bisa tersebar ke clone lokal, cache CI, fork, log, artifact, dan sistem analitik. Walaupun file kemudian dihapus pada commit berikutnya, secret tersebut tetap ada di riwayat sampai dilakukan pembersihan yang lebih menyeluruh.

Menjalankan Gitleaks di CI berguna karena:

  • Feedback cepat di pull request: developer tahu sebelum merge.
  • Kebijakan konsisten: semua perubahan diperiksa dengan aturan yang sama.
  • Lebih murah dibanding remediation penuh: rotasi secret dan pembersihan history biasanya lebih mahal daripada mencegah commit sejak awal.
  • Cocok untuk banyak jenis secret: token GitHub, API key pihak ketiga, private key, access key cloud, koneksi database, dan pola rahasia lain.

Namun ada trade-off. Pemindaian yang terlalu luas bisa memperlambat pipeline, sementara aturan yang terlalu ketat dapat memicu false positive. Karena itu, implementasi yang baik harus menyeimbangkan kecepatan, akurasi, dan disiplin tim.

Apa yang sebenarnya dideteksi oleh Gitleaks

Gitleaks mendeteksi secret berdasarkan kombinasi pola teks, entropi, dan aturan yang dikenal umum. Ia efektif untuk kasus seperti:

  • Token akses dan personal access token
  • API key layanan pihak ketiga
  • Access key atau secret key cloud
  • Private key dalam format umum
  • Kredensial yang hardcoded di file konfigurasi
  • Nilai sensitif yang muncul di file YAML, JSON, env, atau source code

Yang perlu dipahami: Gitleaks bukan sistem klasifikasi semantik penuh. Ia tidak selalu tahu apakah sebuah string memang aktif, kadaluarsa, atau hanya data dummy. Karena itu hasil scan harus diperlakukan sebagai sinyal keamanan yang kuat, bukan kebenaran absolut tanpa verifikasi.

Kapan scan sebaiknya dijalankan

1. Saat pull request dibuka atau diperbarui

Ini adalah titik paling penting. Tujuannya bukan hanya menemukan secret, tetapi menghentikan merge sampai temuan ditinjau. Untuk sebagian besar tim, scan pada event pull_request memberi rasio manfaat terhadap biaya terbaik.

2. Saat push ke branch utama

Lapisan ini berguna sebagai pengaman tambahan. Kadang ada merge manual, direct push terbatas, atau workflow yang tidak melewati PR. Scan di push membantu menangkap kasus tersebut.

3. Secara terjadwal

Untuk repository lama atau monorepo besar, jadwal harian atau mingguan berguna untuk mendeteksi perubahan aturan, file lama yang baru teridentifikasi, atau regresi konfigurasi. Ini bukan pengganti scan PR, melainkan pelengkap.

4. Sebelum rilis atau pembuatan artifact

Jika pipeline Anda menghasilkan image, package, atau deployment bundle, menempatkan scan sebelum tahap publikasi dapat mencegah artefak berisi konfigurasi sensitif ikut tersebar.

Workflow GitHub Actions yang praktis

Contoh berikut menjalankan Gitleaks saat pull request dan push ke branch utama. Workflow ini sengaja sederhana agar mudah diadopsi lebih dulu, lalu bisa diperluas sesuai kebutuhan tim.

name: secret-scan

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  gitleaks:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Run Gitleaks
        uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          args: detect --source . --config .gitleaks.toml --redact --verbose

Ada beberapa detail penting pada contoh di atas:

  • fetch-depth: 0 membantu jika Anda ingin pemindaian yang mempertimbangkan history atau diff yang lebih lengkap. Jika hanya ingin lebih cepat untuk perubahan terbatas, Anda bisa meninjau apakah shallow checkout cukup.
  • --config .gitleaks.toml membuat aturan dapat dikendalikan tim dan ditinjau bersama.
  • --redact berguna agar nilai secret tidak tampil utuh di log CI.
  • --verbose membantu saat awal implementasi dan debugging, tetapi pastikan log tetap aman.

Jika ingin fokus pada perubahan terbaru di PR agar lebih cepat, sebagian tim memilih memindai commit range atau hasil diff, bukan seluruh repository. Trade-off-nya: lebih cepat, tetapi ada risiko tidak menangkap secret lama yang baru tersentuh secara tidak langsung. Untuk repository baru, memindai keseluruhan source sering masih masuk akal. Untuk repo besar, strategi bertahap biasanya lebih realistis.

Struktur konfigurasi dasar Gitleaks

File .gitleaks.toml memungkinkan Anda menambahkan aturan organisasi, path yang diabaikan, atau pengecualian tertentu. Contoh minimal berikut cukup untuk memulai tanpa membuat konfigurasi terlalu rumit.

title = "Gitleaks config"

[allowlist]
description = "Global allowlist"
paths = [
  '''^docs/''',
  '''^testdata/'''
]

[[rules]]
id = "generic-api-key"
description = "Generic API key assignment"
regex = '''(?i)(api[_-]?key|token|secret)\s*[:=]\s*["']?[A-Za-z0-9_\-]{16,}["']?'''
tags = ["key", "token"]

Tujuan konfigurasi dasar ini bukan untuk menutupi semua kasus, melainkan memberi titik awal yang bisa dipahami tim. Beberapa catatan penting:

  • Jangan terlalu cepat menambah banyak regex kustom. Aturan yang agresif sering memicu false positive tinggi.
  • Batasi allowlist ke path atau kasus yang benar-benar dipahami. Jangan menjadikan allowlist sebagai tempat menyembunyikan masalah.
  • Simpan konfigurasi dalam repository agar perubahan aturan bisa direview lewat pull request.

Mengintegrasikan ke alur pull request

Tujuan utamanya adalah feedback cepat. Idealnya, developer melihat status check gagal beberapa menit setelah membuka atau memperbarui PR, bukan setelah merge. Agar ini efektif:

  1. Jalankan scan pada event pull_request.
  2. Jadikan job sebagai required status check pada branch protection untuk branch utama.
  3. Tampilkan pesan kegagalan yang jelas: file, rule, dan langkah perbaikan.
  4. Gunakan redaksi log yang aman agar secret tidak bocor ulang di output CI.

Jika organisasi menggunakan review wajib, secret scan sebaiknya diposisikan sebagai pemeriksaan otomatis sebelum reviewer manusia menghabiskan waktu. Ini mengurangi beban reviewer untuk mencari kesalahan yang sebenarnya bisa ditemukan mesin.

Contoh output temuan dan cara membacanya

Berikut contoh keluaran yang disederhanakan. Format aktual bisa berbeda tergantung opsi dan integrasi yang dipakai, tetapi informasi intinya serupa.

Finding:     api_key = "sk_live_xxxxxxxxxxxxx"
RuleID:      generic-api-key
File:        config/payment.yml
Line:        12
Commit:      1a2b3c4d
Author:      developer@example.com
Message:     add payment config

Yang perlu diperhatikan dari output seperti ini:

  • File dan line menunjukkan lokasi sumber masalah paling cepat untuk diperbaiki.
  • RuleID membantu menentukan apakah ini temuan valid atau false positive dari aturan tertentu.
  • Commit penting untuk investigasi jika secret ternyata sudah tersebar ke branch lain atau artifact.

Jika Anda mengaktifkan --redact, nilai secret seharusnya tidak tampil utuh. Ini penting karena log CI sendiri dapat menjadi sumber kebocoran baru bila tidak dijaga.

Strategi baseline untuk repository lama

Repository yang sudah berumur biasanya memiliki dua masalah: riwayat commit panjang dan temuan lama yang banyak. Jika Anda langsung menerapkan kebijakan gagal untuk seluruh history, tim bisa kewalahan. Di sinilah strategi baseline berguna.

Pendekatan yang umum dipakai

  • Scan penuh sekali, lalu catat temuan lama sebagai baseline.
  • Mulai fail hanya untuk temuan baru pada pull request dan push berikutnya.
  • Bersihkan baseline secara bertahap berdasarkan risiko: secret aktif lebih dulu, lalu yang sudah kadaluarsa atau dummy tetapi tetap tidak semestinya ada.

Intinya, baseline mencegah tim lumpuh oleh utang lama, tanpa membiarkan kebocoran baru terus terjadi. Namun baseline harus diperlakukan sebagai kompromi sementara, bukan alasan untuk menunda perbaikan tanpa batas.

Hal yang perlu diperhatikan

  • Dokumentasikan siapa yang boleh memperbarui baseline.
  • Tinjau ulang baseline secara berkala.
  • Bedakan antara secret aktif dan secret historis yang sudah tidak berlaku; prioritas penanganannya berbeda.
  • Jangan menyimpan nilai rahasia mentah dalam file baseline atau log tambahan.

Fail policy: kapan pipeline harus gagal

Kebijakan gagal harus jelas sejak awal agar tidak menimbulkan debat setiap ada temuan. Untuk sebagian besar tim, pendekatan berikut cukup masuk akal:

Kebijakan yang disarankan

  • PR gagal jika ada temuan baru yang tidak masuk pengecualian yang sah.
  • Push ke branch utama gagal bila terdeteksi secret baru.
  • Temuan lama dalam baseline tidak menggagalkan PR, tetapi tetap dilacak untuk remediation.

Pendekatan ini menjaga disiplin tanpa memblokir seluruh pengembangan karena utang masa lalu. Jika Anda mengelola sistem dengan regulasi lebih ketat, kebijakan bisa dibuat lebih keras, tetapi konsekuensinya adalah kebutuhan triase yang lebih tinggi.

Kapan pengecualian bisa diterima

Pengecualian layak dipertimbangkan jika:

  • Nilai adalah data contoh yang jelas tidak valid dan tidak dapat digunakan.
  • File berada di folder fixture atau testdata yang memang berisi pola mirip secret, tetapi sudah disanitasi.
  • Aturan terlalu generik dan memicu false positive yang konsisten pada format tertentu.

Meski begitu, pengecualian harus spesifik. Lebih aman mengecualikan satu file fixture yang diketahui aman dibanding menonaktifkan satu rule untuk seluruh repository.

Cara membuat pengecualian yang aman

Pengecualian yang buruk adalah yang terlalu luas, sulit diaudit, atau diberikan tanpa konteks. Prinsip dasarnya:

  • Pilih cakupan sekecil mungkin: file tertentu lebih baik daripada direktori besar; fingerprint tertentu lebih baik daripada menonaktifkan seluruh kategori.
  • Tambahkan alasan di pull request atau dokumentasi konfigurasi.
  • Review berkala untuk memastikan pengecualian masih relevan.

Kesalahan umum adalah mengabaikan seluruh folder konfigurasi atau menambahkan banyak path ke allowlist hanya untuk membuat pipeline hijau. Ini mengorbankan tujuan utama deteksi secret.

Mengurangi false positive tanpa menurunkan perlindungan terlalu jauh

False positive tidak bisa dihilangkan sepenuhnya, tetapi bisa dikurangi dengan pendekatan yang disiplin:

1. Gunakan aturan bawaan seperlunya, lalu tambah kustom secara bertahap

Mulai dari set aturan yang umum, lalu amati pola temuan. Tambahkan aturan organisasi hanya jika ada kebutuhan nyata dan data pendukung.

2. Pisahkan file test dan fixture

Jika tim sering menyimpan contoh payload atau response mock, letakkan di path yang konsisten agar mudah dikelola dalam allowlist sempit.

3. Gunakan data dummy yang jelas

Untuk dokumentasi atau sample config, gunakan placeholder seperti YOUR_API_KEY_HERE, bukan string yang menyerupai credential sungguhan.

4. Redaksi log dan review output

Terkadang false positive baru terlihat jelas ketika Anda melihat file dan konteksnya. Pastikan output cukup informatif untuk triase, tetapi tetap aman.

5. Hindari hardcode yang menyerupai secret

UUID, hash, atau token dummy yang terlalu realistis sering memicu deteksi. Jika nilainya tidak perlu realistis, sederhanakan formatnya.

Langkah remediation setelah secret benar-benar bocor

Jika Gitleaks menemukan secret yang valid, fokus utama bukan hanya memperbaiki commit, tetapi menganggap secret itu sudah terkompromi. Menghapus file dari branch saat ini saja tidak cukup.

  1. Rotasi atau cabut secret segera. Ini langkah terpenting. Token, API key, dan kredensial cloud yang bocor harus dianggap tidak aman lagi.
  2. Ganti penggunaan secret dengan mekanisme yang benar, misalnya GitHub Actions Secrets, secret manager cloud, atau variabel environment dari sistem deployment.
  3. Hapus secret dari kode dan file konfigurasi.
  4. Tinjau riwayat Git jika secret sudah masuk commit sebelumnya. Untuk kasus tertentu, perlu pembersihan history menggunakan alat yang sesuai dan koordinasi dengan seluruh tim.
  5. Periksa dampak sebaran: artifact CI, image container, cache, log, atau salinan di fork.
  6. Audit akses jika secret memberi akses ke sistem penting. Lihat apakah ada aktivitas mencurigakan setelah waktu kebocoran.

Catatan: Menghapus commit dari history bisa mengganggu kolaborasi dan membutuhkan force push serta sinkronisasi ulang clone lokal. Karena itu pencegahan di PR jauh lebih murah daripada pembersihan setelah merge.

Praktik yang sebaiknya dipadukan dengan Gitleaks

Secret scanning di CI akan lebih efektif jika digabung dengan praktik berikut:

  • Pre-commit hook lokal untuk feedback sebelum push. Ini mempercepat loop developer, meski tetap tidak boleh menjadi satu-satunya kontrol.
  • GitHub Actions Secrets atau secret manager eksternal agar nilai sensitif tidak disimpan di repository.
  • Template konfigurasi seperti .env.example tanpa nilai nyata.
  • Review branch protection agar status check wajib benar-benar ditegakkan.
  • Pendidikan tim tentang jenis file yang rawan bocor: .env, file credential cloud, private key, export Postman, file YAML deployment, dan konfigurasi lokal.

Kesalahan umum saat implementasi

  • Hanya scan branch utama dan melewatkan pull request.
  • Tidak memakai redaksi output sehingga log CI justru membocorkan nilai secret.
  • Allowlist terlalu luas demi mengurangi noise secara instan.
  • Menganggap secret aman setelah file dihapus padahal masih ada di history atau artifact.
  • Tidak punya prosedur remediation sehingga tim bingung saat temuan valid muncul.
  • Tidak membedakan repo baru dan repo lama; baseline yang tepat penting untuk adopsi bertahap.

Rekomendasi implementasi untuk tim

Jika Anda ingin mulai dengan biaya adopsi rendah, urutannya bisa seperti ini:

  1. Buat file .gitleaks.toml minimal.
  2. Tambahkan workflow GitHub Actions untuk pull_request dan push.
  3. Aktifkan --redact dan jadikan status check wajib.
  4. Lakukan scan awal untuk memahami profil temuan repository.
  5. Jika repo lama, terapkan baseline dan fail hanya pada temuan baru.
  6. Review false positive selama 1-2 iterasi, lalu sempitkan pengecualian seperlunya.
  7. Dokumentasikan prosedur rotasi secret dan pembersihan history bila insiden terjadi.

Pendekatan ini biasanya cukup untuk memberi nilai nyata tanpa langsung membuat pipeline kompleks. Setelah proses stabil, Anda bisa menambah integrasi lain seperti notifikasi, artifact laporan, atau pre-commit hook lokal.

Penutup

Deteksi secret bocor di CI dengan Gitleaks dan GitHub Actions bukan sekadar menambah satu job keamanan di pipeline, tetapi membangun kebiasaan engineering yang lebih aman. Kunci keberhasilannya ada pada penempatan scan di pull request, kebijakan gagal yang tegas tetapi realistis, baseline untuk repository lama, serta pengecualian yang sempit dan bisa diaudit.

Tooling membantu, tetapi hasil akhirnya tetap bergantung pada disiplin tim: tidak menyimpan secret di repository, merotasi credential yang bocor, dan meninjau aturan secara berkala. Jika diterapkan dengan benar, Anda mendapat feedback cepat tanpa mengorbankan alur kerja pengembangan secara berlebihan.