How to Write a Backstage Software Template

A Backstage software template turns a portal form into a new repo complete with CI and a catalog entry.

Define a Template entity with parameters (the form) and steps (fetch template, publish to GitHub, register in the catalog). Developers pick it in Backstage and get a paved-road repo.

Steps

• Declare parameters for the fields you collect (name, owner).
• Use fetch:template to render skeleton files.
• Use publish:github to create the repo.
• Use catalog:register to add it to the software catalog.

Template entity

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: node-service
  title: Node service (paved road)
spec:
  parameters:
    - title: Service details
      required: [name, owner]
      properties:
        name: { type: string }
        owner: { type: string }
  steps:
    - id: fetch
      action: fetch:template
      input:
        url: ./skeleton
        values: { name: ${{ parameters.name }} }
    - id: publish
      action: publish:github
      input:
        repoUrl: github.com?owner=my-org&repo=${{ parameters.name }}
    - id: register
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
        catalogInfoPath: /catalog-info.yaml

Gotchas

• The skeleton directory must contain a catalog-info.yaml for catalog:register to find.
• Actions like publish:github require the scaffolder to hold a token with repo-create scope.

Related guides