Backstage SpringBoot模板执行publish:gitlab步骤时集成配置匹配失败

问题场景 #

我创建了如下Backstage模板，用于基于https://gitlab.com/handson-backstage/sf-rest-template的自定义SpringBoot starter项目创建新服务，并将新项目推送到https://gitlab.com/handson-backstage/${{parameters.component_id}}：

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name:  spring-boot-service
  title: Spring Boot Service
  description: Create a new Spring Boot service
  tags:
    - spring-boot
spec:
  owner: guest
  type: service

  parameters:
    - title: Fill in the following parameters for your new service
      required:
        - component_id
        - description
      properties:
        component_id:
          title: Name of the service
          type: string
          description: Unique name of the new service.
        description:
          title: Description of the service
          type: string
          description: Description of the new service.

  steps:
    - id: fetch-base
      name: Fetch Base
      action: fetch:plain
      input:
        url: https://gitlab.com/handson-backstage/sf-rest-template

    - id: publish
      name: Publish
      action: publish:gitlab
      input:
        repoUrl: 'https://gitlab.com/handson-backstage/${{parameters.component_id}}'
        token: some_token

执行模板时第二步报错，错误日志：

2023-06-15T08:53:48.000Z Beginning step Publish2023-06-15T08:53:48.000Z InputError: No matching integration configuration for host https, please check your integrations config    
at parseRepoUrl (webpack-internal:///../../plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/util.ts:58:15)    
at Object.handler (webpack-internal:///../../plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/gitlab.ts:130:97)    
at NunjucksWorkflowRunner.executeStep (webpack-internal:///../../plugins/scaffolder-backend/src/scaffolder/tasks/NunjucksWorkflowRunner.ts:211:26)    
at process.processTicksAndRejections (node:internal/process/task_queues:95:5)    
at async NunjucksWorkflowRunner.execute (webpack-internal:///../../plugins/scaffolder-backend/src/scaffolder/tasks/NunjucksWorkflowRunner.ts:281:17)    
at async TaskWorker.runOneTask (webpack-internal:///../../plugins/scaffolder-backend/src/scaffolder/tasks/TaskWorker.ts:90:33)    at async run (/Users/ghassentdf/Desktop/Workspace/Projects/backstage/node_modules/p-queue/dist/index.js:163:29)

错误原因 #

1. publish:gitlab动作要求repoUrl使用Backstage标准化的GitLab仓库格式，而非完整的HTTPS URL。直接传入https://gitlab.com/...会导致解析逻辑错误识别主机为https，而非gitlab.com，进而找不到对应的集成配置。
2. 模板中硬编码token的方式不符合规范，publish:gitlab会自动读取Backstage集成配置中对应GitLab主机的token，无需手动指定。

解决步骤 #

1. 修正模板中的repoUrl格式 #

将repoUrl改为Backstage支持的GitLab仓库格式，有两种可选写法：

• 格式1：gitlab:<host>/<owner>/<repo>
• 格式2：<host>?repo=<owner>/<repo>

修改后的publish步骤：

- id: publish
  name: Publish
  action: publish:gitlab
  input:
    repoUrl: 'gitlab:gitlab.com/handson-backstage/${{parameters.component_id}}'

2. 在Backstage配置文件中添加GitLab集成 #

找到Backstage的app-config.yaml（或app-config.production.yaml），添加GitLab集成配置，建议用环境变量存储token以保证安全：

integrations:
  gitlab:
    - host: gitlab.com
      token: ${GITLAB_TOKEN}

然后在运行Backstage的环境中设置GITLAB_TOKEN环境变量，值为具有创建仓库权限的GitLab个人访问令牌。

3. 移除模板中的硬编码token #

删除publish步骤中的token: some_token行，因为publish:gitlab会自动使用集成配置里的token。

修改后的完整模板 #

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name:  spring-boot-service
  title: Spring Boot Service
  description: Create a new Spring Boot service
  tags:
    - spring-boot
spec:
  owner: guest
  type: service

  parameters:
    - title: Fill in the following parameters for your new service
      required:
        - component_id
        - description
      properties:
        component_id:
          title: Name of the service
          type: string
          description: Unique name of the new service.
        description:
          title: Description of the service
          type: string
          description: Description of the new service.

  steps:
    - id: fetch-base
      name: Fetch Base
      action: fetch:plain
      input:
        url: https://gitlab.com/handson-backstage/sf-rest-template

    - id: publish
      name: Publish
      action: publish:gitlab
      input:
        repoUrl: 'gitlab:gitlab.com/handson-backstage/${{parameters.component_id}}'

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