Pada proyek API yang kompleks, perubahan autentikasi, webhook, atau retry sering kali tersembunyi di berganti-ganti branch. Untuk menjaga kontrak auth tetap valid, kita harus menjawab langsung: bagaimana Git workflow membuktikan setiap perubahan tidak merusak flow otentikasi dan webhook yang sudah ada?

Dengan mengikuti kerangka review Git yang konsisten—berangkat dari branch policy, deskripsi perubahan hingga checklist idempotensi—tim dapat mencegah regresi autentikasi sebelum kode mencapai main. Artikel ini menunjukkan langkah-langkah praktis untuk menanamkan validasi tersebut dalam setiap merge.

Mengidentifikasi Problem Git Workflow yang Terlalu Santai

Referensi menggarisbawahi pola umum: review longgar, deskripsi PR samar, dan kecepatan merge yang mengabaikan konteks. Untuk kontrak API auth, kelemahan ini berarti perubahan header, token, atau retry akan diterima tanpa audit yang memadai.

Solusinya bukan menambah layer tool, melainkan memperjelas proses review: siapa memeriksa, apa yang harus disebutkan, dan data apa yang harus diverifikasi. Poin-poin di bawah menata kelola tersebut.

Buat Kebijakan Review Branch untuk Kontrak Auth

1. Branch Protection Berdasarkan Scope Auth/Webhook/Retry

Pisahkan branch tujuan berdasarkan fungsi: main untuk release stabil, auth/* untuk perubahan auth, webhook/* untuk endpoint event, dan retry/* untuk logika resubmission. Proteksi branch kemudian mensyaratkan dua reviewer dengan satu dari tim keamanan atau integrasi.

Gunakan status checks untuk memastikan tes contract auth (misal suite Postman atau Pact) lulus sebelum merge, sehingga review tidak hanya manual tapi juga mencakup automasi validasi.

2. Template Deskripsi PR yang Fokus pada Kontrak

Berikut template sederhana yang dapat ditambahkan pada pengaturan repository:

- Area Perubahan: [Auth / Webhook / Retry / Infrastruktur]
- Perubahan Schema: [Ya/Tidak] (jelaskan tabel atau struktur JSON)
- Flow Auth Terdampak: (header, token refresh, middleware)
- Tes Contract: (nama suite dan hasil)
- Dampak pada Webhook: (endpoint, signature, retry)
- Penjamin Idempotensi: (apa saja yang dicek)

Dengan menuntut jawaban rinci, reviewer akan otomatis memikirkan bagian yang paling sensitif.

Checklist Idempotensi dan Validasi Flow

Untuk setiap PR yang menyentuh kontrak API auth, gunakan checklist yang ditempel di bagian akhir deskripsi atau ditautkan ke dokumentasi tim:

  • Identity header tetap konsisten: periksa header wajib (Authorization, X-Client-ID) dan pastikan middleware baru tidak menimpanya.
  • Replay/Retry harus deteksi: perubahan retry harus mencantumkan bagaimana idempotensi dicapai (token unik, sequence number).
  • Webhook signature tetap valid: list webhook yang test-nya dijalankan dan secret rotation jika ada.
  • Schema auditable: perubahan JSON schema harus disertai dengan dokumentasi versi schema.

Checklist ini bisa diwujudkan sebagai file CONTRACT_REVIEW.md di repository dan dijadikan template PR agar reviewer tahu checklist mana yang harus diverifikasi.

Mengelola Schema dan Catatan Merge

Schema Registry dan Versi Schema

Setiap perubahan schema auth atau webhook wajib disertai catatan versi. Misalnya satu file schema/auth-schema.yml vs schema/auth-schema-v2.yml dengan metadata last-reviewed dan compatibility.

Tambahkan script kecil untuk memeriksa kompatibilitas saat PR dibuat:

#!/bin/sh
npm run validate-schema auth-schema.yml --output=json

Script ini dijalankan dalam pipeline PR agar reviewer tidak harus membuka schema secara manual.

Contoh Catatan Merge yang Memverifikasi Auth Flow

Berikut contoh catatan merge yang dapat digunakan reviewer untuk dokumentasi internal:

Merge: feature/auth-token-rotation
Verified:
- Flow: token perlu refresh di /auth/refresh, header Authorization tetap diproksi
- Contract tests: auth-flow-suite (Pass)
- Webhook signature: unchanged, retry limit 3, idempotent request ID
- Schema: auth-schema-v1.3.yml (compat dengan v1)

Catatan seperti ini bisa dimasukkan ke changelog atau release note sehingga siapa pun dapat menelusuri alasan perubahan.

Mitigasi agar Git Workflow Tidak Merusak Integrasi

Untuk menjaga integrasi tetap utuh, tambahkan pengingat berikut ke dokumentasi Git team:

  1. Jangan merge kalau checklist tidak lengkap: Linting dan contract suite harus hijau sebelum reviewer menyetujui.
  2. Gunakan PR review otomatis untuk perubahan sensitive: tag khusus ([AUTH], [WEBHOOK]) memicu reviewer khusus.
  3. Rollback plan selalu siap: setiap merge yang menyentuh auth disertai rollback command (misal revert commit dan re-run migrations).

Selain itu, tim harus melakukan post-merge review mingguan untuk melihat apakah checklist digunakan dan apakah ada false positive pada automasi. Review rutin membantu deteksi bila tim mulai mengabaikan prosedur.

Kesimpulan

Kontrak API auth, webhook, dan retry menjadi titik kritis yang sering terlewat bila praktik Git review tidak konsisten. Dengan menetapkan branch policy berbasis scope, mendesain template PR yang memaksa penjelasan, dan mendokumentasikan checklist idempotensi serta catatan merge, tim dapat memastikan perubahan tidak merusak flow yang sudah ada. Pendekatan ini menjaga integrasi tetap valid tanpa mengandalkan proses manual yang rentan kelupaan.