Belajar Backstage - Software Templates (Scaffolder) Dasar

#Pendahuluan

Di episode 5, kalian menyaksikan bagaimana catalog ingestion dan processing mengubah file catalog-info.yaml yang mentah menjadi entity katalog yang hidup, lengkap dengan processor dan relasi antar entity. Episode 6 menggeser fokus dari mencatat yang sudah ada menjadi menciptakan yang baru: kita masuk ke Software Templates, yang akrab disebut Scaffolder. Di sinilah Backstage berubah dari direktori pasif menjadi alat yang aktif membangun. Dengan satu template, kalian menggantikan puluhan halaman wiki tentang cara memulai komponen baru — dan semua orang memulai dari titik yang sama, dengan standar yang sama.

#Konsep Golden Path

#Satu Jalan, Banyak Variasi

Golden path adalah istilah untuk satu cara resmi membuat dan mengembangkan sebuah komponen. Bukan berarti semua komponen harus identik — parameter memungkinkan variasi — tetapi infrastruktur di sekitar komponen selalu terstandar. Setiap komponen baru yang lahir lewat golden path sudah membawa struktur folder yang benar, konfigurasi CI yang siap pakai, dan entri katalog, tanpa harus diingatkan satu per satu.

Scaffolder mewujudkan golden path ini lewat template: sebuah entity khusus di katalog (kind Template) yang mendeskripsikan apa yang akan dibuat, pertanyaan apa yang akan diajukan ke user, dan rangkaian langkah apa yang akan dijalankan untuk membuatnya.

#Anatomi Template

Template YAML tersusun dari empat bagian utama:

• metadata — identitas template: nama, judul, deskripsi, dan owner.
• parameters — form schema yang ditampilkan ke user sebagai formulir isian.
• steps — daftar langkah yang dijalankan berurutan oleh scaffolder.
• output — hasil yang disajikan ke user setelah scaffolding selesai.

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: example-react-service
  title: Contoh Service React
  description: Golden path untuk service React sederhana
  tags:
    - react
    - service
spec:
  owner: group:platform-team
  type: website
  parameters:
    - title: Informasi Dasar
      properties:
        name:
          type: string
          title: Nama Service
          description: Nama unik untuk service ini
  steps:
    - id: fetch-base
      name: Ambil Base Template
      action: fetch:template
      input:
        url: ./templates/react
        values:
          name: ${{ parameters.name }}
  output:
    links:
      - title: Repository Service
        url: https://github.com/example/${{ parameters.name }}

Perhatikan blok di atas: parameters mendefinisikan satu field name, langkah fetch-base memanggil action fetch:template, dan output menghasilkan sebuah link ke repository. Semua bagian itu kita bedah satu per satu.

#Parameter dan Form Schema

#Form Schema dari Properties

Bagian parameters ditulis mengikuti JSON Schema. Backstage otomatis menerjemahkannya menjadi formulir di UI: setiap property menjadi satu field, tipe data menentukan jenis inputnya (string, integer, boolean, array, object), dan title beserta description menjadi label serta teks bantuan. Tidak ada satu baris pun kode frontend yang perlu kalian tulis untuk formulir ini — backend scaffolder yang membangunnya.

parameters:
  - title: Detail Service
    required:
      - name
    properties:
      name:
        type: string
        title: Nama Service
        minLength: 3
      repoUrl:
        type: string
        title: Lokasi Repository
      description:
        type: string
        title: Deskripsi
        description: Tidak wajib, tetapi sangat disarankan

#Nilai User Menjadi Placeholder

Nilai yang diisi user di formulir tersedia sebagai placeholder selama eksekusi template. Placeholder memakai sintaks khusus scaffolder, dan karena sifatnya mengandung tanda dollar serta kurung kurawal, ia hanya boleh berada di dalam blok kode — di blok contoh di atas kalian melihatnya di bagian values dan output. Saat user mengisi field name dengan payment-api, maka seluruh kemunculan placeholder tersebut diganti menjadi payment-api pada saat langkah dieksekusi.

Untuk mengontrol urutan dan perilaku formulir, scaffolder mendukung properti berawalan ui: seperti ui:order, ui:autofocus, ui:help, dan ui:widget — semua memperhalus pengalaman mengisi form tanpa menulis komponen React manual.

#Steps dan Output

Bagian steps adalah daftar langkah yang dijalankan secara berurutan. Setiap langkah memiliki id yang unik, name yang tampil di UI, action yang menentukan action yang dipanggil, dan input yang berisi parameter untuk action tersebut. Urutan di dalam daftar adalah urutan eksekusi — langkah kedua baru dimulai setelah langkah pertama selesai.

Bagian output mendefinisikan apa yang disajikan ke user setelah semua langkah selesai. Bentuk paling umum adalah links yang menunjuk ke repository, pipeline, atau dokumentasi, dan text sebagai pesan ringkasan. Ada juga entities untuk entity yang akan didaftarkan ke catalog — konsep ini akan diperdalam di episode 10.

#Actions Bawaan

Scaffolder dilengkapi kumpulan action bawaan yang siap dipakai. Action adalah unit kerja terkecil — satu langkah memanggil satu action. Yang paling penting untuk pemula:

Di luar keenam di atas masih ada banyak action lain untuk GitLab, Azure DevOps, Kubernetes, hingga anggota keluarga debug:* lainnya, tetapi keenam ini adalah fondasi yang cukup untuk memahami alur Scaffolder.

#Workflow Scaffolding Sederhana

#Tiga Langkah Standar

Workflow scaffolding paling sederhana dan paling umum terdiri dari tiga langkah berurutan: fetch base template, publish ke GitHub, lalu register entity ke catalog. Rangkailah semuanya dalam satu steps:

steps:
  - id: fetch-base
    name: Ambil Base Template
    action: fetch:template
    input:
      url: ./templates/react
      values:
        name: ${{ parameters.name }}
        owner: ${{ parameters.owner }}
 
  - id: publish
    name: Publikasikan ke GitHub
    action: publish:github
    input:
      repoUrl: ${{ parameters.repoUrl }}
      defaultBranch: main
 
  - id: register
    name: Daftarkan ke Catalog
    action: catalog:register
    input:
      repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
      catalogInfoPath: /catalog-info.yaml

Perhatikan bagaimana langkah register mengambil output dari langkah publish lewat steps.publish.output.repoContentsUrl — output sebuah langkah bisa menjadi input langkah berikutnya. Inilah cara data mengalir di sepanjang pipeline.

#Mendaftarkan Template ke Catalog

Sebelum bisa dipakai dari UI, template itu sendiri harus terdaftar di katalog sebagai entity Template. Prosesnya sama seperti mendaftarkan komponen biasa: menunjuk lokasi file yang berisi entity Template.

curl -X POST "http://localhost:7007/api/catalog/locations" \
  -H "Content-Type: application/json" \
  -d '{"target": "https://github.com/example/backstage-templates/blob/main/templates/react-service/template.yaml"}'

Setelah terdaftar, template akan muncul di halaman Create Backstage, dan user tinggal menekan tombol, mengisi formulir, lalu menunggu pipeline selesai.

#Penutup

Pada episode 6 ini, kalian membangun fondasi Scaffolder: konsep golden path dan cara template mewujudkannya, anatomi template YAML dengan metadata, parameters, steps, dan output, form schema yang otomatis menjadi formulir, placeholder nilai user, action bawaan seperti fetch:template, publish:github, catalog:register, dan debug:*, serta workflow scaffolding tiga langkah yang paling umum.

Inti yang harus dibawa pulang:

• Template adalah entity catalog — agar bisa dipakai, ia harus terdaftar sebagai entity Template di katalog.
• Parameter mengalir lewat placeholder — nilai form user menjadi placeholder yang diganti saat eksekusi; output satu langkah bisa menjadi input langkah berikutnya.
• Alur paling umum adalah fetch-publish-register — ambil base template, terbitkan ke repository, lalu daftarkan ke catalog.
• Action debug:* adalah sahabat debugging — gunakan debug:log untuk melihat nilai yang benar-benar dipegang scaffolder.

Di episode 7 berikutnya, kita membangun lapisan dokumentasi di atas komponen yang kalian scaffold: TechDocs — bagaimana Backstage mengubah dokumentasi menjadi bagian dari alur kerja, dibangun langsung dari sumbernya, dan selalu sinkron dengan kode.