Pendahuluan

Untuk menjaga kualitas API GraphQL, lint schema perlu dijalankan setiap kali ada perubahan. Artikel ini langsung menjawab: bangun pipeline CI/CD yang otomatis memvalidasi schema, mengecek contract, dan mengelola versi schema sebelum rilis. Fokusnya adalah memastikan lint berhasil, contract tetap kompatibel, dan versi schema terdokumentasi sebelum masuk cabang utama.

Lint schema GraphQL bukan sekadar gaya; ia mendeteksi kesalahan struktural, field duplikat, dan pola antipattern yang bisa rusak di runtime. Dengan mencampurkannya ke pipeline, Anda menangkap masalah di tahap pra-merge sehingga downstream consumer tidak terdampak.

Langkah-langkah Pipeline CI/CD

1. Lint Schema Otomatis

Gunakan tooling seperti graphql-schema-linter atau graphql-cli untuk mengecek aturan statis. Integrasikan perintah lint di stage pipeline yang berjalan setelah kode disinkronkan.

jobs:
  lint-schema:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install dependencies
        run: npm install
      - name: Lint schema
        run: npx graphql-schema-linter --schema schema.graphql --rules no-deprecated-fields

Perintah ini otomatis gagal jika aturan dilanggar. Gunakan konfigurasi rule di file lint untuk menjaga konsistensi antar tim.

2. Verifikasi Contract dengan Tooling dan Snapshot

Contract verification menegaskan bahwa perubahan masih kompatibel dengan consumer. Pilih salah satu strategi:

  • Comparator schema seperti Apollo Rover atau graphql-cli diff membandingkan schema saat ini dengan versi sebelumnya.
  • Schema snapshot yang dijalankan lewat GraphQL Code Generator untuk menghasilkan tipe dan memvalidasi field yang dihapus.

Implementasi umum dalam pipeline:

      - name: Compare schema vs baseline
        run: |
          npx graphql-cli diff --config graphql.config.js --schema schema.graphql

Jika diff menunjukkan penghapusan bidang kritis, pipeline harus gagal atau menandai breaking change. Keputusan ini bisa dikaitkan dengan approval manual agar tim menyediakan mitigasi.

3. Rilis Versi Schema

Setelah lint dan contract berhasil, rilis versi schema merupakan bentuk dokumentasi teknis. Best practice versioning:

  • Gunakan semantic versioning khusus untuk schema, misalnya 1.2.0-schema.
  • Catat perubahan breaking/non-breaking di changelog atau folder schema/versions.
  • Update tag Git otomatis dengan versi schema baru.

Penerapan otomatis di pipeline:

      - name: Bump schema version
        run: |
          npm run bump-schema -- --path schema.graphql

Script ini dapat membaca perubahan dan memutuskan patch/minor/major berdasarkan diffs.

Integrasi dengan Git Workflow

Supaya pipeline relevan, hubungkan dengan Git workflow:

  • Pre-merge validation: Jalankan lint + contract saat pull request dibuat. Gunakan badge status untuk memberi tahu PR reviewer.
  • PR validation: Pastikan lint dijalankan di branch feature/ sebelum merge ke main. Jika PR memodifikasi schema, tambahkan trigger tambahan untuk checklist schema.
  • Protected branch: Aktifkan gate yang memerlukan status pipeline "lint-schema", "contract-check", dan review sebelum merge.

Checklist operasional:

  • Lint schema berhasil tanpa warning.
  • Contract verification: tidak ada breaking change atau direview secara manual.
  • Version schema diperbarui dan didokumentasikan.
  • Pipeline PR menandai status "ready" sebelum merge.

Gating Criteria sebelum Deployment Produksi

Sebelum deployment, pastikan kriteria berikut tercapai:

  • Lint pass: Semua lint langsung menghentikan pipeline jika gagal.
  • Contract verification: Perubahan schema dibanding baseline minimal divergen. Untuk breaking change, sertakan approval tambahan.
  • Schema version diterbitkan: Tag otomatis dan changelog diupdate sebagai bukti rilis.
  • Dokumentasi consumer: Perbarui tipe GraphQL di repositori client atau gateway.

Tambahkan gate manual seperti "Schema owner approval" jika perubahan terlalu besar.

Tips Operasional dan Best Practices

  • Satu sumber kebenaran: Simpan schema tunggal (misal schema/schema.graphql) agar lint, diff, dan generator menggunakan file sama.
  • Storage versi schema: Retransfer schema ke artifact repo (Artifactory, S3) agar tim lain bisa mengunduh versi spesifik.
  • Debugging lint failure: Perhatikan pesan lint, jalankan local dengan npx graphql-schema-linter --rules untuk mengecek rule mana gagal.
  • Tooling pilihan: GraphQL Code Generator cocok untuk men-generate tipe dari schema versi release, sementara Apollo Rover efisien untuk contract check di federasi.

Kesimpulan

Otomasi lint schema GraphQL dalam pipeline CI/CD memberi jaminan awal bagi tim. Gabungkan lint, contract verification, dan versioning dengan gate yang jelas, sehingga perubahan schema sudah tervalidasi sebelum mencapai produksi. Dengan checklist lint-prerequisites dan tooling yang dipilih sesuai kebutuhan (graphql-schema-linter untuk lint, Apollo Rover untuk diff, dan GraphQL Code Generator untuk tipe), pipeline menjadi mekanisme pencegahan kesalahan yang efektif.