Tujuan release flow GraphQL otomatis adalah memastikan schema yang masuk sudah tervalidasi, men-trigger release hanya jika lint berhasil, serta memberikan observabilitas agar regresi cepat terdeteksi. Artikel ini membahas langkah-langkah praktis, tooling yang direkomendasikan, struktur pipeline, dan observabilitas ringan yang cukup bagi tim engineering.

Arsitektur Release Flow GraphQL Otomatis

Alur release yang ideal dimulai dari kode aplikasi atau schema yang disimpan di cabang fitur. Setiap push memicu pipeline CI di mana linting, schema compare, dan unit test API dijalankan. Hanya ketika semua tahapan ini sukses, deploy ke environment staging atau production boleh dijalankan.

Flow-nya terdiri dari:

  1. Lint schema dan parsing.
  2. Validasi terhadap schema baseline (misal trunk/staging).
  3. Deploy otomatis dengan gating pada job lint.
  4. Observabilitas pasca-deploy untuk metrics dan log.

Lint dan Validasi Schema Secara Otomatis

Untuk lint dan validasi schema, kombinasi GraphQL Inspector dan Apollo CLI cukup populer. GraphQL Inspector dapat memeriksa breaking change dan lint rule, sementara Apollo CLI bisa mengelola schema registry serta validasi terhadap versi yang tersimpan.

Contoh script lint

#!/bin/bash
set -e
npx graphql-inspector lint schema.graphql --rules=schema
npx graphql-inspector diff schema.graphql --base trunk.schema.graphql --critical
npx apollo service:check --service=my-service --key=$APOLLO_KEY

Script di atas: (1) lint schema lokal, (2) membandingkan dengan schema trunk untuk mendeteksi breaking change, dan (3) mengecek ke registry Apollo untuk memverifikasi perubahan tidak melanggar contract.

Menangani schema drift

Schema drift terjadi ketika definisi schema yang di-deploy berbeda dari yang seharusnya. Untuk mengatasinya:

  • Selalu simpan schema trunk di repository atau registry (Apollo/GraphQL Inspector).
  • Gunakan job diff untuk fail pipeline ketika drift terdeteksi.
  • Berikan notifikasi ke tim lewat Slack/email jika diff gagal, sertakan hasil diff untuk debugging.

Struktur Pipeline CI/CD untuk Release Flow

Berikut contoh job GitHub Actions yang menjalankan lint dan trigger release hanya saat lint sukses.

name: GraphQL Release Flow
on:
  push:
    branches:
      - main
jobs:
  validate-schema:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install dependencies
        run: npm ci
      - name: Lint schema
        run: ./scripts/graphql-lint.sh
  deploy:
    needs: validate-schema
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4
      - name: Deploy ke staging
        run: ./scripts/deploy-staging.sh

Job deploy hanya berjalan kalau validate-schema sukses. Pendekatan ini menghindari deploy dengan schema rusak. Untuk GitLab CI, struktur serupa bisa dibuat menggunakan stages: dan needs:.

Tooling Pilihan Selama Tahap CI

Beberapa tooling yang bisa dipertimbangkan:

  • GraphQL Inspector: lint, diff, lint rules custom. Cocok untuk pipeline lint standar.
  • Apollo CLI: menghubungkan ke schema registry, mengenali breaking change via service:check, dan bisa memicu gate release.
  • GraphQL Code Generator: memastikan tipe dan operasi valid; jalankan di job terpisah untuk memastikan typing sync dengan schema.

Pilih GraphQL Inspector apabila ingin lint dan diff dalam satu alat ringan. Gunakan Apollo CLI bila memiliki schema registry dan ingin mengikat rilis ke contract. GraphQL Codegen berguna saat proyek menggunakan kode yang dikomunikasikan lewat TypeScript/Java.

Observabilitas Pasca-Deploy

Observabilitas memastikan tim mengetahui regresi setelah release. Fokus pada tiga hal: metrics, log, dan alert.

Metrics penting

  • Latency per operasi (query/mutation) untuk memantau degradasi performa.
  • Error rate dari GraphQL response error atau HTTP status 500.
  • Field resolver failures jika menggunakan instrumentation seperti OpenTelemetry atau Apollo Tracing.

Gunakan exporter atau client library (misalnya @apollo/server dengan plugins) untuk mengekspor ke Prometheus/Grafana.

Logging dan alert

Tambahkan middleware untuk menambahkan konteks lintas trace ID. Catat query name, user ID, dan status code. Kirim log ke aggregator (Loki, Elasticsearch). Buat alert bila error rate atau latency melebihi threshold selama beberapa interval.

Observabilitas ringan yang cukup

  1. Expose health endpoint untuk probe readiness.
  2. Gunakan tracing sederhana dari Apollo untuk mencatat durasi resolvers.
  3. Pasang alert email atau Slack ketika schema check job gagal atau deploy job timeout.

Checklist Release dan Rollback

Setiap release harus dicek dengan checklist berikut:

  • Lint dan diff berhasil tanpa breaking change.
  • Unit/integration test utama jalan.
  • Schema registry mencatat versi terbaru.
  • Deploy monitoring aktif dan metrics terkirim.

Jika ditemukan regresi, lakukan rollback dengan langkah ringkas ini:

  1. Gagal job observabilitas: kubectl rollout undo deployment/my-app atau revert release otomatis.
  2. Jika schema drift: revert commit schema dan update branch trunk.
  3. Reset pipeline: atur tag versi lama dan push kembali untuk memicu job release.

Rollback checklist memastikan aturan release tetap konsisten sambil meminimalisasi downtime.

Penutup

Dengan linting dan schema validation di pipeline CI, release flow GraphQL bisa dicegah dari breaking change. Observabilitas yang terukur membantu tim mendeteksi regresi lebih cepat. Tooling seperti GraphQL Inspector, Apollo CLI, dan GraphQL Codegen menjembatani linting, schema drift, dan integrasi dengan registry. Tetap monitoring metrics dan log setelah deploy, dan siapkan checklist rollback agar release tetap dapat diandalkan.