Golden Paths: Software Templates

1. 1

   The template: parameters

   The form a developer sees. OwnerPicker lists Groups from the catalog, so every new service has a real owner. Validation (pattern, length) prevents names that would break DNS or Kubernetes.

   apiVersion: scaffolder.backstage.io/v1beta3
   kind: Template
   metadata:
     name: spring-boot-service
     title: New Spring Boot service (golden path)
     description: Production-ready Java service with CI, GitOps, dashboards and docs.
     tags: [java, recommended]
   spec:
     owner: group:team-platform
     type: service
     parameters:
       - title: About the service
         required: [name, owner, description]
         properties:
           name:
             type: string
             title: Service name
             pattern: '^[a-z][a-z0-9-]{2,30}$'
             ui:help: lowercase, dashes, 3–31 chars (used for repo, DNS and k8s names)
           description: { type: string, title: What does it do? }
           owner:
             type: string
             title: Owning team
             ui:field: OwnerPicker
             ui:options: { catalogFilter: { kind: Group } }
           system:
             type: string
             title: System
             ui:field: EntityPicker
             ui:options: { catalogFilter: { kind: System } }
           exposePublicly: { type: boolean, title: Expose at <name>.shoplite.dev?, default: false }
     steps:
       - id: fetch
         name: Render service skeleton
         action: fetch:template
         input:
           url: ./skeleton
           values:
             name: ${{ parameters.name }}
             owner: ${{ parameters.owner }}
             system: ${{ parameters.system }}
             description: ${{ parameters.description }}
       - id: publish
         name: Create GitHub repo
         action: publish:github
         input:
           repoUrl: github.com?owner=shoplite&repo=${{ parameters.name }}
           defaultBranch: main
           repoVisibility: internal
           protectDefaultBranch: true
           requireCodeOwnerReviews: true
       - id: gitops
         name: Render GitOps config
         action: fetch:template
         input:
           url: ./gitops
           targetPath: ./gitops
           values:
             name: ${{ parameters.name }}
             expose: ${{ parameters.exposePublicly }}
       - id: gitops-pr
         name: Open PR in shoplite-gitops
         action: publish:github:pull-request
         input:
           repoUrl: github.com?owner=shoplite&repo=shoplite-gitops
           branchName: add-${{ parameters.name }}
           title: "Add ${{ parameters.name }} (from golden path)"
           description: Created by Backstage for ${{ parameters.owner }}.
           sourcePath: ./gitops
           targetPath: apps/${{ parameters.name }}
       - id: register
         name: Register in catalog
         action: catalog:register
         input:
           repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
           catalogInfoPath: /catalog-info.yaml
     output:
       links:
         - { title: Repository, url: ${{ steps.publish.output.remoteUrl }} }
         - { title: GitOps PR, url: ${{ steps['gitops-pr'].output.remoteUrl }} }
         - { title: Open in catalog, icon: catalog, entityRef: ${{ steps.register.output.entityRef }} }

2. 2

   The skeleton: templated files

   Files under skeleton/ are rendered with ${{ values.x }}. The CI workflow CALLS a reusable workflow owned by the platform team, so improving CI later updates every service at once.

   name: release
   on:
     push: { branches: [main] }
     pull_request: {}
   jobs:
     golden-path:
       uses: shoplite/platform-workflows/.github/workflows/java-service.yml@v4
       with:
         service: ${{ values.name }}
         java-version: "21"
       secrets: inherit

3. 3

   Register the template and try it

   Add the template repo as a catalog location. It appears under Create. Run it with a test name and watch each step's log.

   catalog:
     locations:
       - type: url
         target: https://github.com/shoplite/shoplite-templates/blob/main/spring-boot-service/template.yaml
         rules: [{ allow: [Template] }]

   terminalcopy cmd

   $ # Backstage UI → Create → 'New Spring Boot service (golden path)' → name: wishlist, owner: team-storefront

   ── expected output ──

   ✔ Render service skeleton 0.4s

   ✔ Create GitHub repo 2.1s

   ✔ Render GitOps config 0.1s

   ✔ Open PR in shoplite-gitops 1.6s

   ✔ Register in catalog 0.8s

   Repository: https://github.com/shoplite/wishlist

   GitOps PR: https://github.com/shoplite/shoplite-gitops/pull/87

4. 4

   Merge the PR and watch it go live

   The ApplicationSet from the GitOps course (Mission 2.3) discovers apps/wishlist and creates the Applications; Kyverno policies pass because the template complies; the HTTPRoute gets DNS and TLS from Mission 0.2.

   terminalcopy cmd

   $ gh pr merge 87 --repo shoplite/shoplite-gitops --squash

   argocd app wait wishlist-in-cluster --health --timeout 600 && curl -s https://wishlist.dev.shoplite.dev/actuator/health

   ── expected output ──

   {"status":"UP"}

Make each change, run the command, and read the error before revealing the diagnosis. Recognising these messages on sight is what makes you fast on a real team. Undo the change afterwards.