Deploy dan CI

Repository ini menerbitkan API statis lewat GitHub Actions, bukan lewat server. Ada dua workflow: deploy yang membangun website dan seluruh berkas JSON lalu menerbitkannya ke branch gh-pages, dan ci yang hanya memverifikasi build website beserta go vet ./.... Keduanya memakai node-version: 22 dan go-version: "1.25" dengan cache aktif (.github/workflows/deploy.yml:18-35¹, .github/workflows/ci.yml:14-19²).

Pemicu workflow deploy

deploy menyala lewat tiga jalan: jadwal mingguan, tombol manual, dan push yang menyentuh berkas tertentu.

(.github/workflows/deploy.yml:1-10³)

Dua pengaman dipasang di level workflow. concurrency memakai group deploy dengan cancel-in-progress: false, jadi run yang sedang jalan tidak pernah dibatalkan dan run berikutnya menunggu giliran. permissions: contents: write dibutuhkan karena job membuat commit baru di branch gh-pages (.github/workflows/deploy.yml:9-10⁴).

Tahapan job deploy

Seluruh langkah berada dalam satu job deploy di ubuntu-latest tanpa needs antar job, sehingga step berjalan serial di satu runner dan kegagalan satu step menghentikan step berikutnya (.github/workflows/deploy.yml:12-15⁵). Urutan itu penting: setiap step membaca artefak yang ditulis step sebelumnya di dalam direktori kerja yang sama.

gantt
    title Urutan step job deploy
    dateFormat HH:mm
    axisFormat %H:%M
    section web
    "actions/checkout@v4"          :s1, 00:00, 1m
    "Setup Node 22"                :s2, after s1, 1m
    "npm ci + npm run build"       :s3, after s2, 1m
    section api
    "Setup Go 1.25"                :s4, after s3, 1m
    "extract-csv 3 SQL dump"       :s5, after s4, 1m
    "generate-static-api -v"       :s6, after s5, 1m
    "cache boundaries zip"         :s7, after s6, 1m
    "generate-boundaries -v"       :s8, after s7, 1m
    "add-has-path -v"              :s9, after s8, 1m
    "generate-missings -v"         :s10, after s9, 1m
    "update-stats -v"              :s11, after s10, 1m
    section publish
    "Assemble publish dir"         :s12, after s11, 1m
    "actions-gh-pages@v4"          :s13, after s12, 1m
%% fig: Urutan step job deploy
%% desc: Setiap step berjalan setelah step sebelumnya karena memakai artefak yang baru ditulis. Panjang bar diseragamkan dan hanya penanda urutan, bukan durasi terukur.

Website dibangun lebih dulu dari web/ dengan npm ci lalu npm run build, memakai cache npm yang dikunci ke web/package-lock.json (.github/workflows/deploy.yml:25-29⁶). Isi direktori web/ sendiri dibahas di Website dan Playground.

Setelah itu enam tool Go dijalankan berurutan, masing-masing diikuti perintah pemeriksaan yang mencetak ukuran atau isi artefaknya ke log. Rincian per tahap, termasuk flag tiap tool, ada di usage tools/main.go (tools/main.go:8-23⁷) dan di Pipeline Generate dengan Go Tools.

Menggabungkan artefak lalu push ke gh-pages

graph LR
  dist["web/dist"] --> deploy["deploy/"]
  api["api/"] --> v2["deploy/v2/"]
  deploy --> pages["branch gh-pages"]
  v2 --> pages
  style dist fill:#8b5cf6,color:#fff
  style api fill:#8b5cf6,color:#fff
  style deploy fill:#f59e0b,color:#000
  style v2 fill:#f59e0b,color:#000
  style pages fill:#336791,color:#fff
%% fig: Komposisi direktori publish
%% desc: Hasil build Astro ditaruh di akar deploy sedangkan berkas JSON API ditaruh di subdirektori v2, lalu keduanya di-push ke branch gh-pages.

Step Assemble publish dir membuat deploy/, menyalin isi web/dist/* ke akarnya, menyentuh berkas deploy/.nojekyll, lalu menyalin api/* ke deploy/v2/ (.github/workflows/deploy.yml:92-104¹⁴). Karena API bersarang di subpath v2, base URL publiknya berakhiran /v2 (README.md:9¹⁵).

Step terakhir memakai peaceiris/actions-gh-pages@v4 dengan publish_dir: ./deploy, publish_branch: gh-pages, dan keep_files: true (.github/workflows/deploy.yml:106-115¹⁶). README menjelaskan rangkaian yang sama: api/ disalin ke deploy/v2/ bersama hasil build web/dist lalu di-push ke gh-pages (README.md:41-42¹⁷).

⚠️ Nama step-nya sendiri adalah Deploy to gh-pages (keep old api/) (.github/workflows/deploy.yml:106¹⁸), dan keep_files: true mempertahankan berkas yang sudah ada di branch tujuan (README.md:592¹⁹). Artinya penerbitan bersifat menambah, bukan menyamakan: berkas JSON lama yang tidak lagi dihasilkan generator tetap tersaji di gh-pages sampai dihapus manual.

⚠️ commit_message di-hardcode deploy: ${{ github.sha }} [cron] (.github/workflows/deploy.yml:115²⁰), sehingga commit hasil push biasa tetap berlabel [cron].

Workflow ci.yml

ci bekerja jauh lebih ringan. Ia menyala pada pull_request dan push ke main/v2 dengan path filter web/**, tools/**, go.mod, memiliki satu job build, dan hanya menjalankan npm ci --prefix web, npm run build --prefix web, lalu go vet ./... (.github/workflows/ci.yml:1-20²¹). Tidak ada langkah generate, tidak ada go build, tidak ada test, dan tidak ada deploy.

Konsekuensinya, kesalahan pada tools/ hanya tertangkap sebagai error kompilasi atau temuan vet, bukan sebagai data yang salah bentuk. Data yang benar-benar tersaji baru terverifikasi saat deploy berjalan dan mencetak ukuran artefak di log.

⚠️ Branch yang dipantau kedua workflow tidak sama. deploy menunggu push ke master dan v2 (.github/workflows/deploy.yml:5-7²²), sedangkan ci menunggu push ke main dan v2 (.github/workflows/ci.yml:5-7²³). README sendiri menyebut push ke main/v2 sebagai pemicu (README.md:663²⁴). Akibatnya push ke master bisa memicu deploy tanpa CI, dan push ke main bisa memicu CI tanpa deploy.