
Backstage Scaffolder でリポジトリ作成を標準化する
前の記事
はじめに
「新しいリポジトリを作るたびに命名規則がバラバラ」
「catalog-info.yaml を書くのを忘れる人がいる」
「README のフォーマットが人によって違う」
こういった問題を解決するのが Backstage の Scaffolder(Software Templates)機能。ウィザード形式の UI からフォームに入力するだけで、リポジトリの作成・ファイル生成・カタログ登録を自動化できる。
この記事では Scaffolder の仕組みと、業務で使う際のポイントをまとめる。
Scaffolder の全体像
開発者がフォームに入力
↓
1. fetch:template → skeleton/ のファイルを変数で展開して生成
2. publish:github → GitHub にリポジトリを作成して push
3. catalog:register → Backstage カタログに自動登録この3ステップが一連の流れで実行される。
テンプレートの構成
terraform-template/
├── template.yaml # テンプレート定義(フォーム・ステップ)
└── skeleton/ # 生成されるファイルの雛形
├── catalog-info.yaml
├── main.tf
├── variables.tf
├── mkdocs.yml
└── docs/index.mdtemplate.yaml の基本構成
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
name: terraform-module
title: "Terraform モジュール 雛形"
description: "AWS Terraform モジュールのリポジトリを自動生成します"
spec:
parameters:
- title: "モジュール設定"
properties:
moduleName:
title: "モジュール名"
type: string
pattern: "^[a-z][a-z0-9-]*$" # 命名規則をバリデーション
lifecycle:
title: "ライフサイクル"
type: string
enum: [experimental, production, deprecated]
default: experimental
- title: "リポジトリ設定"
properties:
repoUrl:
title: "リポジトリの場所"
type: string
ui:field: RepoUrlPicker
ui:options:
allowedHosts:
- github.com
allowedOwners:
- my-org # ← ここが重要(後述)
steps:
- id: fetch-base
name: "ファイル生成"
action: fetch:template
input:
url: ./skeleton
values:
moduleName: ${{ parameters.moduleName }}
repoUrl: ${{ parameters.repoUrl }} # ← values に明示的に渡す
- id: publish
name: "GitHub にプッシュ"
action: publish:github
input:
repoUrl: ${{ parameters.repoUrl }}
defaultBranch: main
repoVisibility: private
- id: register
name: "カタログ登録"
action: catalog:register
input:
repoContentsUrl: ${{ steps['publish'].output.repoContentsUrl }}
catalogInfoPath: "/catalog-info.yaml"
output:
links:
- title: "生成されたリポジトリ"
url: ${{ steps['publish'].output.remoteUrl }}skeleton/ のテンプレート変数
`skeleton/` 内のファイルでは `${{ values.xxx }}` で変数を埋め込める。
# skeleton/catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: terraform-module-${{ values.moduleName }}
annotations:
github.com/project-slug: ${{ (values.repoUrl | parseRepoUrl).owner }}/${{ (values.repoUrl | parseRepoUrl).repo }}
backstage.io/techdocs-ref: dir:.
spec:
type: library
lifecycle: ${{ values.lifecycle }}
owner: group:default/infra-team# skeleton/main.tf
# terraform-module-${{ values.moduleName }}
# 自動生成日: ${{ "" | now }}
terraform {
required_version = ">= 1.0"
}ハマりポイント①: `parameters` と `values` は別物
最もハマりやすいポイント。
`skeleton/` 内のテンプレートで使えるのは `values.xxx` のみ。`parameters.xxx` は参照できない。
# fetch-base ステップで values に渡す
- id: fetch-base
input:
values:
moduleName: ${{ parameters.moduleName }}
repoUrl: ${{ parameters.repoUrl }} # ← 忘れずに渡す`values` に渡し忘れると skeleton 内で `undefined` になり、以下のエラーが出る:
InputError: No matching integration configuration for host undefinedエラーメッセージから原因を特定しにくいため注意。
ハマりポイント②: `allowedOwners` を設定しないと危ない
`allowedOwners` を設定しないと、フォームの `owner` フィールドが自由入力になる。
`publish:github` は指定した `owner` へのアクセス権がない場合、エラーにならずトークン所有者のアカウントにフォールバックしてリポジトリを作成する。
owner に "wrong-org" を入力
↓
wrong-org へのアクセス権なし
↓
トークン所有者の個人アカウントに作成される(エラーにならない)業務では意図しないアカウント配下にリポジトリが散らばるリスクがある。
対策:
ui:options:
allowedHosts:
- github.com
allowedOwners:
- my-org # ドロップダウン選択になり自由入力不可になる`allowedOwners` を設定するとフィールドがドロップダウン選択になり、指定した Org 以外には作れなくなる。
業務で整備すべきこと
命名規則をバリデーションで強制する
moduleName:
type: string
pattern: "^[a-z][a-z0-9-]*$" # 小文字英数字とハイフンのみ
minLength: 3
maxLength: 50フォームのバリデーションで命名規則を強制できるため、後から「リポジトリ名の統一キャンペーン」をする必要がなくなる。
catalog-info.yaml を必ず生成させる
skeleton に `catalog-info.yaml` を含めることで、作成されるリポジトリには必ずカタログエントリが存在する状態にできる。
テンプレートの種類を用意する
用途別にテンプレートを用意することで、どのテンプレートを使えばいいか迷わなくなる。
Scaffolder がもたらす変化
一度テンプレートを整備してしまえば、以降の新規リポジトリは自動的に標準に準拠した状態で生まれる。
まとめ
Scaffolder の本質は「ゴールデンパス(正しい道)を作ること」。
すべての開発者が毎回ベストプラクティスを調べなくても、フォームに入力するだけで標準的な構成のリポジトリが作れる状態にする。これが積み重なると、組織全体のリポジトリ品質が底上げされる。
まず1つテンプレートを作ってみることをお勧めしたい。
次の記事