Create RFC template

Template

Actions used

You can check the available actions if you visit /templates/actions.

Walkthrough

You can use this template by registering it from roadie-demo/scaffolder-examples repo

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: create-rfc-template
  title: Create a new RFC flavored markdown document
  description: Create a new RFC flavored markdown document
spec:
  owner: group:default/engineering
  type: service

  parameters:
    - title: Document front content
      properties:
        rfcNumber:
          title: rfcNumber
          type: string
        rfcTitle:
          title: RFC Title
          type: string
        abstract:
          title: Document Abstract (optional draft version)
          type: string
          ui:widget: textarea
    - title: Repository to place document
      properties:
        repoUrl:
          content:
            type: string
          description: Name of repository
          ui:field: RepoUrlPicker
          ui:options:
            allowedHosts:
              - github.com

  steps:
    - id: log-message
      name: Log Message
      action: debug:log
      input:
        message: Creating ${{ parameters.rfcNumber }}/index.md

    - id: fetch-template
      action: fetch:template
      input:
        url: https://github.com/roadie-demo/scaffolder-examples/tree/main/create-rfc/skeleton
        templateFileExtension: true
        targetPath: docs/rfcs/${{ parameters.rfcNumber }}
        values:
          rfcNumber: ${{ parameters.rfcNumber }}
          rfcTitle: ${{ parameters.rfcTitle }}
          abstract: ${{ parameters.abstract }}

    - id: move-rfc
      action: fs:rename
      input:
        files:
          - from: docs/rfcs/${{ parameters.rfcNumber }}/template.md
            to: docs/rfcs/${{ parameters.rfcNumber }}/index.md

    - id: create-pull-request
      name: create-pull-request
      action: publish:github:pull-request
      input:
        repoUrl: ${{ parameters.repoUrl }}
        branchName: RFC-${{ parameters.rfcNumber }}_${{ parameters.rfcTitle | replace(" ", "-") | replace("\"", "") | replace ("'", "") | lower }}
        title: RFC-${{ parameters.rfcNumber }} - ${{ parameters.rfcTitle }}
        description: ${{ parameters.abstract }}

Breakdown

Parameters

This section configures the frontend for your template. Essentially these values will be provided from the backstage ui to the template.

param This renders 3 separate input fields for the template.

- title: Document front content
  properties:
    rfcNumber:
      title: rfcNumber
      type: string
    rfcTitle:
      title: RFC Title
      type: string
    abstract:
      title: Document Abstract (optional draft version)
      type: string
      ui:widget: textarea

param This uses a custom ui:field option to provide a repository url.

- title: Repository to place document
  properties:
    repoUrl:
      content:
        type: string
      description: Name of repository
      ui:field: RepoUrlPicker
      ui:options:
        allowedHosts:
          - github.com

Steps

debug:log

Uses the debug:log action to output a log message to the backstage scaffolder UI. The message text is coming from the rfcNumber parameter that is provided by the user.

- id: log-message
  name: Log Message
  action: debug:log
  input:
    listWorkspace: false
    message: Creating ${{ parameters.rfcNumber }}/index.md

fetch:template

Uses the fetch:template. It fetches the template skeleton from the hardcoded URL and puts everything into the docs/rfcs/<rfcnumber> folder. The provided values object will be used to replace the values inside the skeleton template by nunjucks.

- id: fetch-template
  action: fetch:template
  input:
    url: https://github.com/roadie-demo/scaffolder-examples/tree/main/create-rfc/skeleton
    templateFileExtension: true
    targetPath: docs/rfcs/${{ parameters.rfcNumber }}
    values:
      rfcNumber: ${{ parameters.rfcNumber }}
      rfcTitle: ${{ parameters.rfcTitle }}
      abstract: ${{ parameters.abstract }}

fs:rename

Uses the fs:rename action. It essentially moves a file inside the current workspace.

- id: move-rfc
  action: fs:rename
  input:
    files:
      - from: docs/rfcs/${{ parameters.rfcNumber }}/template.md
        to: docs/rfcs/${{ parameters.rfcNumber }}/index.md

publish:github:pull-request

Uses the publish:github:pull-request action. It opens a PR with the current workspace as the payload. Make sure your branchName is unique each time you run this action.

- id: create-pull-request
  name: create-pull-request
  action: publish:github:pull-request
  input:
    repoUrl: ${{ parameters.repoUrl }}
    branchName: RFC-${{ parameters.rfcNumber }}_${{ parameters.rfcTitle | replace(" ", "-") | replace("\"", "") | replace ("'", "") | lower }}
    title: RFC-${{ parameters.rfcNumber }} - ${{ parameters.rfcTitle }}
    description: ${{ parameters.abstract }}