Backstage模板中使用GitHub PR动作执行catalog:register报错求助

问题背景 #

我基于@backstage/plugin-scaffolder-backend-module-github插件创建了Backstage模板，通过生成GitHub Pull Request将新组件注册到Backstage目录。相关配置如下：

模板Workflow配置 #

- id: publish
  name: Publish
  action: publish:github:pull-request
  input:
    repoUrl: ${{ parameters.repoUrl }}
    branchName: ${{ parameters.branch }}
    title: "Scaffold new code into existing repo"
    description: "Generated from Backstage template"

- id: register
  name: Register
  action: catalog:register
  input:
    repoContentsUrl: ${{ steps['publish'].output.repoContentsUrl }}
    catalogInfoPath: '/catalog-info.yaml'

对应的catalog-info.yaml #

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: backstage
  description: An example of a Backstage application.
spec:
  type: website
  owner: john@example.com
  lifecycle: experimental

报错日志 #

2025-12-06T05:27:56.211Z Beginning step Fetch Base
2025-12-06T05:27:56.216Z info: Fetching template content from remote URL
2025-12-06T05:27:56.223Z info: Listing files and directories in template
2025-12-06T05:27:56.225Z info: Processing 3 template files/directories with input values {"name":"test3"}
2025-12-06T05:27:56.236Z info: Writing file catalog-info.yaml to template output path with mode 33188.
2025-12-06T05:27:56.238Z info: Writing file index.js to template output path with mode 33188.
2025-12-06T05:27:56.239Z info: Writing file package.json to template output path with mode 33188.
2025-12-06T05:27:56.240Z info: Template result written to /var/folders/nb/sxwmfr6s5r3fn1dc992jp4s00000gn/T/7672915b-0f75-4820-a493-a01dab070a3f
2025-12-06T05:27:56.243Z Finished step Fetch Base
2025-12-06T05:27:56.243Z Beginning step Publish
2025-12-06T05:28:00.542Z Finished step Publish
2025-12-06T05:28:00.545Z Beginning step Register
2025-12-06T05:28:00.555Z InputError: Invalid input passed to action catalog:register, instance is not any of [subschema 0],[subschema 1]
    at NunjucksWorkflowRunner.executeStep (/Users/user1/test/backstage/backstage/node_modules/@backstage/plugin-scaffolder-backend/src/scaffolder/tasks/NunjucksWorkflowRunner.ts:342:19)
    at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
    at async NunjucksWorkflowRunner.execute (/Users/user1/test/backstage/backstage/node_modules/@backstage/plugin-scaffolder-backend/src/scaffolder/tasks/NunjucksWorkflowRunner.ts:522:9)
    at async TaskWorker.runOneTask (/Users/user1/test/backstage/backstage/node_modules/@backstage/plugin-scaffolder-backend/src/scaffolder/tasks/TaskWorker.ts:219:26)
    at async run (/Users/user1/test/backstage/backstage/node_modules/p-queue/dist/index.js:163:29)

已排查确认publish:github:pull-request的输出仅包含repoUrl，没有repoContentsUrl，但替换为repoUrl作为输入后问题依旧。

错误分析 #

catalog:register动作接受两种合法输入格式（对应报错中的两个subschema）：

1. 直接传入entity字段，提供完整的实体YAML内容
2. 传入repoUrl + catalogInfoPath，但要求repoUrl必须是Backstage标准格式（如github.com?repo=owner/repo-name&owner=owner），而publish:github:pull-request输出的repoUrl是普通GitHub仓库URL（如https://github.com/owner/repo-name），不符合格式要求，导致输入验证失败。

另外，即使格式正确，因为PR处于未合并的新分支，默认情况下catalog:register会拉取仓库主分支的文件，找不到新生成的catalog-info.yaml，也会导致后续问题。

解决方案 #

方法1：构造符合要求的Backstage标准repoUrl #

从publish步骤输出的普通GitHub URL中提取所有者和仓库名，构造标准格式的repoUrl，同时指定PR分支的ref参数：

- id: register
  name: Register
  action: catalog:register
  input:
    # 拆分URL获取owner和repo名，构造标准格式
    repoUrl: "github.com?repo=${{ steps['publish'].output.repoUrl | split('/') | last }}&owner=${{ steps['publish'].output.repoUrl | split('/') | nth(-2) }}"
    catalogInfoPath: '/catalog-info.yaml'
    # 指定PR分支，确保拉取正确的文件版本
    ref: ${{ parameters.branch }}

方法2：直接传递生成的实体内容 #

跳过URL处理，直接将模板生成的catalog-info.yaml内容作为entity参数传入：

- id: register
  name: Register
  action: catalog:register
  input:
    # 从Fetch Base步骤读取生成的catalog-info.yaml内容
    entity: ${{ steps['fetch'].output.files['catalog-info.yaml'].content }}

注：这里的fetch对应日志中的Fetch Base步骤，需确保步骤ID一致。

方法3：使用PR文件的Raw URL（若插件支持） #

部分版本的publish:github:pull-request会输出prUrl，可基于此构造文件的Raw URL作为repoContentsUrl：

- id: register
  name: Register
  action: catalog:register
  input:
    repoContentsUrl: "${{ steps['publish'].output.prUrl }}/files/catalog-info.yaml"
    catalogInfoPath: '/catalog-info.yaml'

注：需确认插件版本是否支持prUrl输出，且格式匹配。

额外验证要点 #

• 修改catalog-info.yaml中的metadata.name为动态值（如${{ parameters.name }}），避免重复注册同名实体
• 确保Backstage拥有访问目标GitHub仓库的权限，能读取对应分支的文件
• 若使用方法1，可通过日志输出确认构造的repoUrl格式正确

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