Internal Developer Platforms Series – Part 15: Backstage Software Templates II

Table of Contents:


After having introduced Software Templates in the last step, it is now time to cover some details about working with the Scaffolder and espacially with parameters and steps.

Backstage parameters

In Backstage Scaffolder, parameters (often referred to as inputs) are values that can be provided by the user when they create a new project using a scaffolder template. These parameters make templates flexible and reusable by allowing customization without modifying the template itself.

Below is an example template that includes parameters and their usage in steps:

kind: Template
  name: my-template
  title: My Template
  description: A template with parameters
    - title: Project Information
          title: Project Name
          type: string
          description: The name of the project
          ui:field: StringInput
          title: Project Description
          type: string
          description: A brief description of the project
          title: Owner
          type: string
          description: The owner of the project
          ui:field: OwnerPicker

    - id: fetch
      name: Fetch Template
      action: fetch:plain
        url: ''
        targetPath: './{{ }}'

    - id: rename
      name: Rename Files
      action: filesystem:rename
          - from: 'old-file-name.txt'
            to: '{{ }}.txt'

    - id: update-readme
      name: Update README
      action: filesystem:replaceInFile
        path: ''
        search: 'PROJECT_NAME'
        replace: '{{ }}'

As described in the last blog post, parameters are defined in the parameters section of the template YAML file. Each parameter has attributes that specify its name, type, description, and other options such as default values and validation rules.

Paramters can be quite flexible: Amont others, you can use textboxes, checkboxes, lists, nested lists. The following screenshots show the formular for a NSX request formular:

Screenshot of a form for creating an NSX Firewall Policy. The progress bar indicates four steps: "NSX Firewall Policy Settings: Basic Settings," "Security Policy Rules," "GitLab Authentication," and "Review." The current step, "Security Policy Rules," displays a section for entering security rules. The NSX Security Rules section includes fields for specifying the rule display name ("rule-1") and the source groups, which consist of IP ranges or CIDRs (e.g., "" and "").
Screenshot of a form section for specifying NSX Firewall Policy Destination Groups. The section includes fields for defining the destination groups by IP, IP range, or CIDR (e.g., ""). It also includes a field for specifying NSX Firewall Policy services ("service-test"), an action field set to "ALLOW," and an option to log the rule action with radio buttons for "Yes" or "No."

Behind the scenes, Backstage Scaffolder uses JSON Schema to define the structure, constraints, and defaults for input parameters. This schema is then used to generate forms automatically using react-jsonschema-form. The form generated by RJSF ensures that the user inputs adhere to the defined schema, providing a seamless and error-free user experience.

Scaffolder steps

Backstage Scaffolder comes with a set of built-in steps. These are actions that can be used within a scaffolder template to automate common tasks. 

A step consists of an id, a name, an action, as well as input and output

You can browse the actions either in the Backstage documentation or in your Backstage instance if you open the URL https://<<backstage-url>>/create/actions

Screenshot of the "Installed Actions" page in the Soeldner Consult application. The page lists various Git-related actions with their input parameters. The "git" action includes parameters for "command," "workingDirectory," "args," and "allowedToFail." The "git
" action has an input parameter for "repoUrl," which specifies the repository URL. The "sc:variables
" action is also listed, but without specified parameters. The interface includes navigation options on the left side for Home, APIs, Docs, and Manage.

When working with steps, it is quite important to familiarize itself with filters that can be used in steps:

The provided built-in filters are used to manipulate and transform data within scaffolding templates. These filters are based on the Nunjucks templating language, which allows for powerful string and data manipulation. Examples for built-in filters are upper, lower, trim or replace, but there are also more sophisticated filters. For example, the parseRepoUrl filter parse a repository URL into its components, such as owner, repository name, and more.

The following is an example of an built-in filter:

- id: log
  name: Parse Repo URL
  action: debug:log
    extra: ${{ parameters.repoUrl | parseRepoUrl }}

Writing and viewing templates is sometimes cumbersome. Luckily, the GUI supports some testing and provides a Template Editor:

Screenshot of the "Manage Components" page in the Soeldner Consult application. The page is used to create, update, and delete components using standard templates. The left navigation bar includes options for Home and APIs. The main section shows "Available Templates" with a search bar and a button labeled "Register Existing Component." A dropdown menu in the top right corner provides options for "Template Editor," "Installed Actions," and "Task List."

You can open the Editor either from the GUI or by navigating to /create/edit page.

The following screenshot shows the Template Editor for the NSX Firewall Scaffolder workflow shown above:

Screenshot of the "Template Editor" page in the Soeldner Consult application. The page allows users to edit, preview, and test templates and template forms. The left side of the screen displays the code for an "NSX Firewall Policy" template, showing parameters and properties such as "display_name," "description," and "owner." The right side shows a form with fields for "NSX Firewall Policy Display Name," "NSX Firewall Policy Description," and "Owner." A progress bar at the top indicates the steps: "NSX Firewall Policy Settings: Basic Settings," "Security Policy Rules," "GitLab Authentication," and "Review." A "Next" button is located at the bottom right.

Built-in Actions

In Backstage Scaffolder, built-in actions are predefined operations that can be used in scaffolding templates to automate tasks during the scaffolding process. These actions are categorized into several types based on their functionality. Below, we show the main categories of built-in actions:

  • Git Actions
  • Fetch Actions
  • Filesystem Actions
  • HTTP Actions
  • Shell Actions
  • Templating Actions
  • Publishing Actions
  • Miscellaneous Actions

The following example shows a Git action to clone a repo.

- id: clone-repo
  name: Clone Repository
  action: git:clone
    url: ''
    branch: 'main'  # Optional
    targetPath: './my-directory'  # Optional

In this blog post, we showed how to work with parameters, steps and actions. In the next blog post, we will show how to create a custom action.

> Click here for Part 16: Backstage Software Templates III


Dr. Guido Söldner


Guido Söldner ist Geschäftsführer und Principal Consultant bei Söldner Consult. Sein Themenfeld umfasst Cloud Infrastruktur, Automatisierung und DevOps, Kubernetes, Machine Learning und Enterprise Programmierung mit Spring.