如何在Backstage脚手架模板步骤中条件添加可选字段？

问题场景 #

需要在Backstage Scaffolder模板的步骤中，根据用户是否提供输入参数动态添加可选字段（而非跳过整个步骤）。例如仅当用户在参数区选择了额外协作者时，才在publish:github步骤中添加collaborators字段。尝试用Nunjucks条件语句实现时，出现YAML解析错误。

原模板代码：

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: example-nodejs-template
  title: Example Node.js Template
  description: An example template for the scaffolder that creates a simple Node.js service
spec:
  owner: user:guest
  type: service

  parameters:
    - title: Fill in some steps
      required:
        - name
      properties:
        name:
          title: Name
          type: string
          description: Unique name of the component
          ui:autofocus: true
          ui:options:
            rows: 5
        collaborators:
          title: Additional collaborators
          type: string
          description: Github team
          ui:field: EntityPicker
          ui:options:
            orderable: false
            catalogFilter:
              - kind: [Group]
                metadata.annotations.github.com/team-slug: { exists: true }

  steps:
    - id: fetch-base
      name: Fetch Base
      action: fetch:template
      input:
        url: ./content
        values:
          name: ${{ parameters.name }}

    - id: publish
      name: Publish
      action: publish:github
      input:
        allowedHosts: ["github.com"]
        description: This is the ${{ parameters.name }}.
        repoUrl: github.com?repo=${{ parameters.name }}&owner=manuviswam
        defaultBranch: main
        collaborators:
          - team: ${{ parameters.collaborators }}
            access: admin

    - 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 }}

尝试的错误写法（导致YAML解析错误）：

- id: publish
      name: Publish
      action: publish:github
      input:
        allowedHosts: ["github.com"]
        description: This is the ${{ parameters.name }}.
        repoUrl: github.com?repo=${{ parameters.name }}&owner=manuviswam
        defaultBranch: main
        {% if parameters.collaborators %}
        collaborators:
          - team: ${{ parameters.collaborators }}
            access: admin
        {% endif %}

问题原因 #

直接在YAML结构中插入块级Nunjucks标签（如{% if %}）会破坏YAML的语法结构。YAML解析器会优先处理模板文件，而这些标签不属于有效的YAML语法，因此直接触发解析错误。

解决方案 #

通过Nunjucks的条件表达式动态生成collaborators字段的值：当用户提供协作者参数时，生成包含权限配置的数组；未提供时，生成空数组（publish:github动作会忽略空数组，不会添加协作者）。

修改后的publish步骤代码：

- id: publish
      name: Publish
      action: publish:github
      input:
        allowedHosts: ["github.com"]
        description: This is the ${{ parameters.name }}.
        repoUrl: github.com?repo=${{ parameters.name }}&owner=manuviswam
        defaultBranch: main
        collaborators: {{ parameters.collaborators ? [{ team: parameters.collaborators, access: 'admin' }] : [] }}

或者使用更易读的块级表达式写法（需保证YAML格式合法，将表达式放在字段值内）：

- id: publish
      name: Publish
      action: publish:github
      input:
        allowedHosts: ["github.com"]
        description: This is the ${{ parameters.name }}.
        repoUrl: github.com?repo=${{ parameters.name }}&owner=manuviswam
        defaultBranch: main
        collaborators: {% if parameters.collaborators %}[{ "team": "${{ parameters.collaborators }}", "access": "admin" }]{% else %}[]{% endif %}

这种写法既符合YAML语法规范，又能根据用户输入动态控制协作者字段的有效内容。

内容的提问来源于stack exchange，提问作者Manu Viswam