メインコンテンツへスキップ
見出し画像

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.md

    template.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` を含めることで、作成されるリポジトリには必ずカタログエントリが存在する状態にできる。

    テンプレートの種類を用意する

    テンプレート用途サービス雛形API サービスの新規作成Terraform モジュール雛形インフラモジュールの新規作成ドキュメントサイト雛形TechDocs 専用リポジトリの作成\begin{array}{|l|l|} \hline \text{テンプレート} & \text{用途} \\ \hline \text{サービス雛形} & \text{API サービスの新規作成} \\ \hline \text{Terraform モジュール雛形} & \text{インフラモジュールの新規作成} \\ \hline \text{ドキュメントサイト雛形} & \text{TechDocs 専用リポジトリの作成} \\ \hline \end{array}

    用途別にテンプレートを用意することで、どのテンプレートを使えばいいか迷わなくなる。


    Scaffolder がもたらす変化

    BeforeAfterリポジトリ作成手順書を見ながら手動で設定フォーム入力のみcatalog-info.yaml を書き忘れる自動生成される命名規則がバラバラバリデーションで強制カタログへの登録を忘れる自動登録される\begin{array}{|l|l|} \hline \text{Before} & \text{After} \\ \hline \text{リポジトリ作成手順書を見ながら手動で設定} & \text{フォーム入力のみ} \\ \hline \text{catalog-info.yaml を書き忘れる} & \text{自動生成される} \\ \hline \text{命名規則がバラバラ} & \text{バリデーションで強制} \\ \hline \text{カタログへの登録を忘れる} & \text{自動登録される} \\ \hline \end{array}

    一度テンプレートを整備してしまえば、以降の新規リポジトリは自動的に標準に準拠した状態で生まれる。


    まとめ

    Scaffolder の本質は「ゴールデンパス(正しい道)を作ること」。

    すべての開発者が毎回ベストプラクティスを調べなくても、フォームに入力するだけで標準的な構成のリポジトリが作れる状態にする。これが積み重なると、組織全体のリポジトリ品質が底上げされる。

    まず1つテンプレートを作ってみることをお勧めしたい。


    次の記事


     
     
    社内インフラ(AWS/Terraform)を管理するしがないエンジニアです。 個人的に試してみたことだったりをつらつらと書き溜めていきます。

    あなたへのおすすめ