Software Templates: the golden path as a form
The catalog tells you what exists. Software Templates create new things the right way: the developer fills in a short form ("name", "owner"), and the scaffolder renders a skeleton repository, pushes it to the git server and registers it in the catalog. This is where a golden path becomes a button.
A template is itself a catalog entity, of kind Template, in scaffolder.backstage.io/v1beta3:
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
name: java-service
title: Java service
description: A Spring Boot service with CI, a bucket and docs
spec:
owner: group:default/platform-team
type: service
parameters:
- title: Service
required: [name, owner]
properties:
name:
title: Name
type: string
pattern: '^[a-z0-9-]+$'
description: Lowercase, digits and dashes - it becomes the repository and the catalog name
owner:
title: Owner
type: string
ui:field: OwnerPicker
ui:options:
catalogFilter:
kind: Group
steps:
- id: fetch
name: Fetch skeleton
action: fetch:template
input:
url: ./skeleton
values:
name: ${{ parameters.name }}
owner: ${{ parameters.owner }}
- id: publish
name: Publish
action: publish:gitlab
input:
repoUrl: git.lab?owner=apps&repo=${{ parameters.name }}
defaultBranch: main
- id: register
name: Register
action: catalog:register
input:
repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
catalogInfoPath: /catalog-info.yaml
output:
links:
- title: Repository
url: ${{ steps.publish.output.remoteUrl }}
- title: Open in catalog
icon: catalog
entityRef: ${{ steps.register.output.entityRef }}
Three parts:
parameters: one or more pages of a form, written as JSON Schema (type,required,pattern,enum), plusui:hints for the frontend (ui:field: OwnerPicker,EntityPicker,RepoUrlPicker). The schema is checked again on the backend when the task is created: a value that does not match is refused with400before anything runs.steps: actions that run in order. Inputs are templated with${{ }}expressions (Nunjucks):parameters.x,steps.<id>.output.y, and filters such asparseRepoUrlandlower.output: links shown when the task finishes.
The built-in actions you will use
| Action | Does | Output |
|---|---|---|
fetch:template | copies a skeleton directory into the task's workspace, rendering ${{ values.x }} in file contents and names | - |
fetch:plain | copies files without templating | - |
publish:gitlab (module scaffolder-backend-module-gitlab) | creates the repository and pushes the workspace as the first commit | remoteUrl, repoContentsUrl, projectId, commitHash |
publish:github (module scaffolder-backend-module-github) | the same on GitHub | remoteUrl, repoContentsUrl |
catalog:register | registers the new catalog-info.yaml | entityRef, catalogInfoUrl |
debug:log | writes a message to the task log | - |
A note on templating: in the template the values come from parameters; in the skeleton (rendered by fetch:template) they come from values - only what the step passed in its values: input. A skeleton that uses ${{ values.team }} while the step only passes name and owner renders an empty string, not an error.
A skeleton catalog-info.yaml:
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: ${{ values.name }}
annotations:
gitlab.com/project-slug: apps/${{ values.name }}
spec:
type: service
lifecycle: experimental
owner: ${{ values.owner }}
repoUrl uses the format the RepoUrlPicker produces: <host>?owner=<group>&repo=<name>. The host must have an integration in app-config.yaml (integrations.gitlab: - host: git.lab); otherwise the step fails with No matching integration configuration for host <host>, please check your integrations config. Note publish:gitlab's default branch is master unless you set defaultBranch.
Running a template
From the UI: Create > choose the template > fill in the form > the task page shows each step's log live. From the API (what the console does for you):
curl -s -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"templateRef":"template:default/java-service","values":{"name":"billing-api","owner":"team-billing"}}' \
http://backstage.lab:7007/api/scaffolder/v2/tasks
The answer is {"id":"<task id>"}. The task runs in the background; read its log:
$ curl -s -H "Authorization: Bearer $TOKEN" http://backstage.lab:7007/api/scaffolder/v2/tasks/$ID/events | jq -r '.[].body.message'
Starting up task with 3 steps
Beginning step Fetch skeleton
Fetching template content from remote URL
Listing files and directories in template
Processing 2 template files/directories with input values
Writing file README.md to template output path with mode 33188.
Writing file catalog-info.yaml to template output path with mode 33188.
Template result written to /tmp/e16c712d-1e12-49e5-af63-fc3487eb8e1f
Finished step Fetch skeleton
Beginning step Publish
Creating repo billing-api in namespace apps.
Init git repository {dir=/tmp/e16c712d-1e12-49e5-af63-fc3487eb8e1f}
Adding file {dir=/tmp/e16c712d-1e12-49e5-af63-fc3487eb8e1f,filepath=.}
Committing file to repo {dir=/tmp/e16c712d-1e12-49e5-af63-fc3487eb8e1f,message=Initial commit}
Pushing directory to remote {dir=/tmp/e16c712d-1e12-49e5-af63-fc3487eb8e1f,remote=origin}
Finished step Publish
Beginning step Register
Registering https://git.lab/apps/billing-api/-/blob/main/catalog-info.yaml in the catalog
Finished step Register
Run completed with status: completed
(mode 33188 is the file mode in decimal: octal 100644, a regular file, rw-r--r--.)
A value that breaks the parameter schema never starts a task:
$ curl -s ... -d '{"templateRef":"template:default/java-service","values":{"name":"Billing API","owner":"team-billing"}}' .../v2/tasks | jq -c '.errors[].stack'
"instance.name does not match pattern \"^[a-z0-9-]+$\""
When a step fails half way
A task is not a transaction. Steps that finished stay done. Two failures every platform team meets:
The repository already exists. Running the same template twice with the same name: publish:gitlab stops with ConflictError: Repository 'billing-api' already exists in namespace 'apps'. Nothing is overwritten - choose another name, or delete the half-made repository first.
The entity is broken. catalog:register first adds the location for real, then asks the catalog to process it as a dry run to find the new entity's name. If the rendered catalog-info.yaml is invalid, the dry run fails and the step ends with:
ResponseError: Request failed with 400 Bad Request
That message hides the cause - the catalog's error is in the response body, not in the task log. And the location stays registered, pointing at a file the catalog keeps rejecting. To see why, dry-run the location yourself (or validate the entity), fix the file in the repository, and let the catalog re-read it. Then fix the template, or the next developer gets the same broken entity.
Testing templates before your users do
- Keep templates in a git repository with merge requests, like code.
- Every parameter that becomes a name gets a
pattern; every field the skeleton uses is passed invalues:. - Render the skeleton's
catalog-info.yamlwith test values andPOSTit to/api/catalog/validate-entityin CI. - Backstage's template editor (reached from the Create page) dry-runs a template through the scaffolder's
/v2/dry-runendpoint: the steps run without side effects (actions that do not support dry-run are skipped).
In an interview: a Software Template is a catalog entity with parameters (a JSON Schema form, validated again on the backend), steps (actions such as fetch:template, publish:gitlab / publish:github, catalog:register, templated with ${{ }}) and output links; the scaffolder runs it as a task. Steps are not transactional, and catalog:register leaves the location behind when the entity is invalid.