Backstage Scaffolder — ゴールデンパスをコードにする方法

  開発者                  Scaffolder UI            Scaffolder Backend
    |                         |                          |
    |--- テンプレート選択 ----->|                          |
    |--- フォーム入力 --------->|                          |
    |                         |--- タスク生成 ------------>|
    |                         |                          |
    |                         |     [stepsを順次実行]      |
    |                         |      1. fetch:template    |
    |                         |      2. publish:github    |
    |                         |      3. catalog:register  |
    |                         |                          |
    |<-- リアルタイムログ -------|<-- ステップ別ログ ---------|
    |<-- outputリンク ---------|<-- 完了 ------------------|
    |                         |                          |
    v                         v                          v
  新リポジトリ + CI + カタログ登録完了 (数分以内)

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: springboot-service
  title: Spring Boot マイクロサービス
  description: 組織標準が組み込まれたSpring Bootサービスを生成します
  tags:
    - java
    - spring-boot
    - recommended
spec:
  owner: group:default/platform-team
  type: service

  parameters:
    - title: サービス基本情報
      required:
        - name
        - description
        - owner
      properties:
        name:
          title: サービス名
          type: string
          pattern: '^[a-z0-9-]+$'
          maxLength: 40
          description: 小文字、数字、ハイフンのみ許可
          ui:autofocus: true
        description:
          title: 説明
          type: string
        owner:
          title: 所有チーム
          type: string
          ui:field: OwnerPicker
          ui:options:
            catalogFilter:
              kind: Group
              spec.type: team
    - title: 技術オプション
      properties:
        javaVersion:
          title: Javaバージョン
          type: string
          default: '21'
          enum: ['17', '21']
        enableKafka:
          title: Kafkaコンシューマを含める
          type: boolean
          default: false

  steps:
    - id: fetch
      name: スケルトンのレンダリング
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.name }}
          description: ${{ parameters.description }}
          owner: ${{ parameters.owner }}
          javaVersion: ${{ parameters.javaVersion }}
          enableKafka: ${{ parameters.enableKafka }}

    - id: publish
      name: GitHubリポジトリの作成
      action: publish:github
      input:
        repoUrl: github.com?owner=acme-corp&repo=${{ parameters.name }}
        defaultBranch: main
        repoVisibility: internal
        protectDefaultBranch: true
        requireCodeOwnerReviews: true

    - id: register
      name: カタログ登録
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps['publish'].output.repoContentsUrl }}
        catalogInfoPath: /catalog-info.yaml

  output:
    links:
      - title: リポジトリを開く
        url: ${{ steps['publish'].output.remoteUrl }}
      - title: カタログで見る
        icon: catalog
        entityRef: ${{ steps['register'].output.entityRef }}

templates/springboot-service/
├── template.yaml
└── skeleton/
    ├── catalog-info.yaml
    ├── README.md
    ├── Dockerfile
    ├── .github/
    │   └── workflows/
    │       └── ci.yaml
    ├── k8s/
    │   ├── deployment.yaml
    │   └── service.yaml
    └── src/main/java/...

# skeleton/catalog-info.yaml (Nunjucksテンプレート)
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: ${{ values.name }}
  description: ${{ values.description | dump }}
  annotations:
    github.com/project-slug: acme-corp/${{ values.name }}
    backstage.io/techdocs-ref: dir:.
spec:
  type: service
  lifecycle: experimental
  owner: ${{ values.owner }}

// skeleton/build.gradle (Nunjucks条件分岐)
dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
    {%- if values.enableKafka %}
    implementation 'org.springframework.kafka:spring-kafka'
    {%- endif %}
}

- id: fetch
  action: fetch:template
  input:
    url: ./skeleton
    copyWithoutTemplating:
      - .github/workflows/*.yaml   # Actionsワークフローは置換なしでコピー
    values:
      name: ${{ parameters.name }}

// plugins/scaffolder-backend-module-acme/src/actions/createJiraTicket.ts
import { createTemplateAction } from '@backstage/plugin-scaffolder-node';

export const createJiraTicketAction = () => {
  return createTemplateAction<{
    projectKey: string;
    summary: string;
    description: string;
  }>({
    id: 'acme:jira:create-ticket',
    description: '新規サービス追跡用のJiraチケットを作成します',
    schema: {
      input: {
        type: 'object',
        required: ['projectKey', 'summary'],
        properties: {
          projectKey: { type: 'string', title: 'Jiraプロジェクトキー' },
          summary: { type: 'string', title: 'チケットタイトル' },
          description: { type: 'string', title: 'チケット本文' },
        },
      },
      output: {
        type: 'object',
        properties: {
          ticketUrl: { type: 'string' },
        },
      },
    },
    async handler(ctx) {
      const { projectKey, summary, description } = ctx.input;
      ctx.logger.info(`Creating Jira ticket in project ${projectKey}`);

      const response = await fetch('https://jira.acme.io/rest/api/2/issue', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          Authorization: `Bearer ${process.env.JIRA_TOKEN}`,
        },
        body: JSON.stringify({
          fields: {
            project: { key: projectKey },
            summary,
            description,
            issuetype: { name: 'Task' },
          },
        }),
      });

      if (!response.ok) {
        throw new Error(`Jira API error: ${response.status}`);
      }
      const issue = await response.json();
      ctx.output('ticketUrl', `https://jira.acme.io/browse/${issue.key}`);
    },
  });
};

// plugins/scaffolder-backend-module-acme/src/module.ts
import { createBackendModule } from '@backstage/backend-plugin-api';
import { scaffolderActionsExtensionPoint } from '@backstage/plugin-scaffolder-node/alpha';
import { createJiraTicketAction } from './actions/createJiraTicket';

export const scaffolderModuleAcme = createBackendModule({
  pluginId: 'scaffolder',
  moduleId: 'acme-actions',
  register(reg) {
    reg.registerInit({
      deps: { scaffolder: scaffolderActionsExtensionPoint },
      async init({ scaffolder }) {
        scaffolder.addActions(createJiraTicketAction());
      },
    });
  },
});

repoUrl:
  title: リポジトリの場所
  type: string
  ui:field: RepoUrlPicker
  ui:options:
    allowedHosts:
      - github.com
    allowedOwners:
      - acme-corp

# .github/workflows/template-ci.yaml
name: template-ci
on:
  pull_request:
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: template.yamlスキーマ検証
        run: npx @roadiehq/backstage-entity-validator validate template.yaml
      - name: スケルトンレンダリングのスモークテスト
        run: |
          # サンプル値でスケルトンをレンダリングした後、
          # 成果物のビルドが通るか確認する
          ./scripts/render-and-build.sh sample-values.json