Software Templatesの作成と管理

Backstageの中核コンセプトで Software Catalog と Entity モデルを理解したうえで、本ドキュメントでは Scaffolder（スキャフォルダー） によるソフトウェアテンプレートの作成・管理・公開を解説します。テンプレートは、組織の「正しいやり方」をゴールデンパス（Golden Path） としてコード化し、新規プロジェクトの立ち上げを数分で完了させる仕組みです。

---

1. Software Templatesとは

Software Templates は、Backstage の Scaffolder プラグインが提供する、新規プロジェクトの自動生成機能です。開発者がフォームに数項目入力するだけで、リポジトリ作成・初期コード生成・CI/CD 設定・カタログ登録までを一括で実行できます。

ゴールデンパス（Golden Path）としての位置づけ

ゴールデンパスとは「組織が推奨する、摩擦の少ない開発の標準ルート」です。テンプレートはこのゴールデンパスを実体化します。

• 認知負荷の削減 — ボイラープレートや初期設定の調査を不要にする。
• 標準の強制ではなく誘導 — 「楽だから自然とそれを選ぶ」状態を作る。
• ベストプラクティスの組み込み — セキュリティ設定・命名規則・オーナー付与を最初から正しい状態にする。

代表的なユースケース

ユースケース	テンプレートが生成するもの
新規マイクロサービス	サービス雛形 + Dockerfile + CI/CD + catalog-info.yaml
共有ライブラリ	パッケージ雛形 + 公開設定 + ドキュメント
IaC モジュール	Terraform モジュール雛形 + レビュー設定
ドキュメントサイト	TechDocs 構成（mkdocs.yml + docs/）

---

2. テンプレートの構造

テンプレートは template.yaml（kind: Template）で定義し、それ自体も 1 つの Entity としてカタログに登録します。

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: dotnet-microservice
  title: .NET マイクロサービス
  description: 標準構成の .NET サービスを生成する
  tags:
    - dotnet
    - recommended
spec:
  owner: group:platform-team
  type: service

  # ① 入力フォーム
  parameters:
    - title: 基本情報
      required:
        - name
      properties:
        name:
          title: サービス名
          type: string
          pattern: '^[a-z][a-z0-9-]*$'
    - title: リポジトリ
      required:
        - repoUrl
      properties:
        repoUrl:
          title: リポジトリの場所
          type: string
          ui:field: RepoUrlPicker
          ui:options:
            allowedHosts:
              - github.com

  # ② 実行ステップ
  steps:
    - id: fetch
      name: テンプレート展開
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.name }}

    - id: publish
      name: リポジトリ作成
      action: publish:github
      input:
        repoUrl: ${{ parameters.repoUrl }}
        description: ${{ parameters.name }} service

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

ブロック	役割
parameters	開発者に見せる入力フォームを JSON Schema で定義する
steps	入力値を使って実行する一連のアクション
output	完了画面に表示するリンクや生成物への導線

skeleton ディレクトリ

実際に展開されるファイル群は skeleton/（任意の名前）に置きます。ファイル内では ${{ values.name }} のような nunjucks テンプレート構文で入力値を埋め込めます。ファイル名自体もテンプレート化可能です（例: ${{ values.name }}.csproj）。

---

3. パラメータ設計

parameters は react-jsonschema-form によってフォーム UI へ変換されます。

フォーム UI とバリデーション

• 複数ページ — parameters を配列にすると、各要素が 1 ステップ（ウィザード）になる。
• バリデーション — pattern、maxLength、enum 等の JSON Schema 標準機能で入力を制約する。
• 入力補助 — ui:help、ui:placeholder、ui:autofocus で UX を整える。

カスタムフィールド

Backstage は Backstage 固有のカスタムフィールドを提供します。

フィールド	用途
RepoUrlPicker	作成先リポジトリ（ホスト・org・リポジトリ名）を選択する
EntityPicker	カタログ上の Entity を選択する（例: オーナーの Group）
OwnerPicker	オーナーになり得る Group / User に絞って選択する
MultiEntityPicker	複数 Entity を選択する

owner:
  title: オーナー
  type: string
  ui:field: OwnerPicker
  ui:options:
    catalogFilter:
      kind: Group

秘密情報は ui:field: Secret で

トークンやパスワードを受け取る場合は ui:field: Secret（ui:widget: password ではなく）を使います。値は ステップ実行時のみメモリ上に保持され、ログやカタログに残りません。

---

4. ビルトインアクション

steps で使う action は、よく使うものが標準で提供されています。

アクション	役割
fetch:template	skeleton を nunjucks で展開してワークスペースに配置する
fetch:plain	テンプレート処理なしでファイルをそのままコピーする
publish:github / publish:gitlab / publish:azure	各 SCM にリポジトリを新規作成してプッシュする
publish:github:pull-request	新規リポジトリではなく 既存リポジトリへの PR を作成する
catalog:register	生成した catalog-info.yaml をカタログに登録する
github:actions:dispatch	生成後に GitHub Actions ワークフローを起動する
debug:log	デバッグ用にログ出力する

カスタムアクションの作成方針

標準アクションで足りない場合（社内 API 呼び出し、独自 SCM 連携など）は カスタムアクション を作成します。

• createTemplateAction を使って TypeScript で実装し、バックエンドに登録する。
• 入力・出力は Zod スキーマ で型付けし、フォーム同様に検証する。
• 既存アクションの組み合わせで実現できないか先に検討し、最小限に留める。

---

5. テンプレートの管理・運用

テンプレート用リポジトリの構成

テンプレートは専用リポジトリ（例: software-templates）にまとめ、1 テンプレート 1 ディレクトリで管理するのが一般的です。

software-templates/
├── dotnet-microservice/
│   ├── template.yaml
│   └── skeleton/          # 実際に展開されるファイル群
│       ├── catalog-info.yaml
│       ├── Dockerfile
│       └── src/...
└── react-frontend/
    ├── template.yaml
    └── skeleton/...

各 template.yaml は app-config.yaml の catalog.locations か、GitHub Discovery で自動登録します。

バージョニングと変更管理

• テンプレートはコードと同様に PR レビュー → マージ で変更する。
• 破壊的変更は metadata.name を変える（例: -v2）か、tags で世代を示す。
• テンプレートで生成済みのリポジトリには変更は遡及しない点に注意（生成は一回限り）。

テスト・CI

• template.yaml の スキーマ検証（backstage-cli）を CI に組み込む。
• 主要テンプレートは実際に生成 → ビルドが通るかを定期的に確認する（ドリフト検知）。

公開範囲・権限

Permission Framework と組み合わせ、「誰がどのテンプレートを実行できるか」を制御できます。機微なテンプレート（本番インフラ作成など）は特定 Group に限定します。

---

6. 組織標準との統合

テンプレートの真価は、組織標準を雛形に埋め込むことで発揮されます。

埋め込む対象	効果
既定の CI/CD パイプライン	全サービスで同じビルド・テスト・デプロイ基盤を使う
セキュリティ設定	SAST・依存関係スキャン・SBOM 生成を初期構成に含める
catalog-info.yaml	カタログ登録漏れをなくし、annotations を自動付与する
mkdocs.yml + docs/	TechDocsを最初から有効化する
オーナー自動付与	OwnerPicker の値を spec.owner に流し込み、所有者不明を防ぐ

annotations の記述漏れを防ぐ

中核コンセプトで触れたとおり、annotations は各プラグインの連携キーです。テンプレートで自動付与すれば、Kubernetes・CI・Dependency-Track などの連携が最初から有効な状態でサービスが生まれます。

---

ベストプラクティス

• テンプレートは「少数・高品質」に保つ — 似たテンプレートが乱立すると選択に迷い、保守も破綻する。共通部分はパラメータで吸収する。
• パラメータは最小限・既定値重視 — 開発者が考えるべき項目を減らす。決められるものは既定値で埋める。
• 保守オーナーを明確化 — テンプレート自体に spec.owner を設定し、陳腐化を防ぐ責任者を置く。
• 生成物の鮮度を CI で検証 — 「生成 → ビルド成功」を定期チェックし、依存の老朽化を検知する。
• アンチパターンを避ける — すべてを 1 つに詰め込んだ巨大テンプレート、ホスト名やトークンのハードコード、Secret を使わない秘密情報の受け渡し。

---

参考リンク

• Software Templates
• Writing Templates
• Builtin actions
• Writing Custom Actions
• Input Examples (RJSF)