Belajar Backstage - Catalog Ingestion & Processing

#Pendahuluan

Di episode 4, kalian mengenal entity dan cara mendeskripsikannya lewat catalog-info.yaml. Pertanyaan selanjutnya: bagaimana entity itu masuk ke catalog? Episode 5 ini membahas catalog ingestion dan processing — mekanisme penyaluran entity (locations dan entity providers) beserta pipeline yang mengubah file mentah menjadi entity siap pakai.

Sebuah catalog hanya berguna jika isinya selalu mutakhir. Karena itu, selain memahami cara menulis entity, kalian perlu memahami dua mekanisme yang menjaga catalog tetap hidup: lokasi yang menunjuk ke sumber, dan pipeline yang mengolahnya secara berkelanjutan.

#Ingestion

Ingestion adalah proses memasukkan entity ke dalam catalog. Ada beberapa pendekatan dengan tingkat kemudahan dan skala yang berbeda. Ketiga pendekatan di bawah tidak saling meniadakan — organisasi sering menggabungkannya: locations untuk entitas khusus, provider untuk seluruh repositori.

#Static Locations

Cara paling sederhana adalah mendeklarasikan lokasi secara statis di app-config.yaml. Setiap lokasi menunjuk langsung ke satu sumber catalog-info.yaml:

catalog:
  locations:
    - type: url
      target: https://github.com/acme/order-service/blob/main/catalog-info.yaml

Static locations mudah dipahami dan cocok untuk entitas yang jumlahnya sedikit. Namun untuk organisasi besar, mendaftarkan setiap repositori secara manual tidak akan bertahan lama.

Lokasi semacam ini juga bisa diregistrasi langsung dari UI katalog — Backstage menyediakan form untuk me-register lokasi baru tanpa mengubah file konfigurasi.

#URL dan File Locations

Location sendiri bisa berupa dua tipe sumber: url untuk sumber jarak jauh (misalnya GitHub, GitLab, atau situs mana pun) dan file untuk file lokal di dalam workspace. Tipe file biasanya dipakai saat kalian ingin me-register entity dari file di mesin atau dari sistem file yang terpasang. Perbedaan keduanya hanya pada sumbernya — proses pengolahan setelahnya identik. Location, apa pun tipenya, hanyalah petunjuk ke mana catalog harus membaca file entity.

#Entity Providers

Untuk skala besar, Backstage menyediakan entity providers — modul yang secara otomatis menemukan dan memasukkan banyak entity sekaligus dari satu sumber. Provider menyediakan berbagai integrasi:

Daripada menunjuk satu per satu, sebuah provider memindai sumbernya, menemukan semua catalog-info.yaml yang cocok, lalu menyerahkan hasilnya ke catalog. Kalian tinggal mengatur pola yang ingin dicari — misalnya semua repositori dalam satu organisasi. Pemilihan provider bergantung pada di mana kalian menyimpan kode: untuk organisasi yang seragam di satu platform, satu provider saja sudah cukup; untuk organisasi campuran, beberapa provider bisa diaktifkan bersamaan.

#Processing Pipeline

Setelah lokasi atau provider menghasilkan sumber entity, kandidat tersebut melewati serangkaian tahap pengolahan yang disebut processing pipeline:

Pipeline ini berjalan terus-menerus: setiap ada perubahan di sumber, entity diperbarui lewat proses yang sama. Alur dari provider hingga stitching inilah yang menjaga catalog tetap sinkron dengan repositori kalian tanpa campur tangan manual.

Urutan tahapan ini bersifat logis, bukan timeline tunggal — beberapa entity bisa berada di tahap berbeda pada waktu yang sama karena pipeline berjalan paralel dan asynchronous.

Kegagalan di salah satu tahap tidak selalu menghentikan seluruh pipeline. Catalog mencatat entity yang gagal diproses dan mencoba lagi secara berkala ketika sumber berubah. Ini berarti entity yang baru saja kalian push bisa butuh beberapa detik sebelum muncul di portal — kondisi normal untuk catalog yang aktif, bukan tanda ada yang rusak.

#Integrasi GitHub Discovery

Kasus paling umum adalah mendiscovery entity dari GitHub. Polanya sama untuk GitLab, Azure DevOps, dan provider lain — hanya nama provider dan sumbernya yang berbeda. Langkah pertama, konfigurasikan integrasi GitHub dan provider discovery di app-config.yaml:

integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN}
 
catalog:
  providers:
    github:
      providerId:
        organization: acme

Langkah kedua, pasang modul backend yang menyediakan provider tersebut:

yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-github

Modul catalog-backend-module-github inilah yang menghubungkan integrasi GitHub dengan pipeline catalog. Setelah modul terpasang dan didaftarkan di backend, setiap repositori di organisasi acme yang berisi catalog-info.yaml akan otomatis muncul sebagai entity di catalog. Pendaftaran di backend mengikuti pola New Backend System yang kalian pelajari di episode 2, yaitu dengan memanggil backend.add() untuk modul yang bersangkutan.

#Penutup

Pada episode 5 ini, kalian memahami cara catalog mengisi dirinya: static locations untuk entitas tunggal, URL dan file locations, serta entity providers untuk discovery otomatis dari GitHub, GitLab, Azure DevOps, Bitbucket, S3, dan file system. Kalian juga mengenal pipeline pengolahan dari entity provider, reading, parsing, validation, relations, hingga stitching.

Inti yang harus dibawa pulang:

• Locations menunjuk sumber — statis untuk yang sederhana, provider untuk skala besar.
• Entity providers mengotomatiskan ingestion — satu konfigurasi bisa menemukan banyak repositori.
• Pipeline adalah proses berkelanjutan — catalog tetap sinkron selama sumber berubah.
• GitHub discovery butuh token — simpan lewat environment variable, bukan di file konfigurasi.

Di episode 6 berikutnya, kalian akan mengubah katalog menjadi mesin produktivitas: Software Templates (Scaffolder) — template YAML dengan golden path yang membiarkan engineer membuat service baru secara self-service, lengkap dengan repositori, pipeline, dan registrasi catalog otomatis.