APC 技術ブログ

株式会社エーピーコミュニケーションズの技術ブログです。

株式会社 エーピーコミュニケーションズの技術ブログです。

トップ > Backstage > Backstageの「Manage Templates(Template Editor)」機能でテンプレート開発サイクルを速くする

Backstageの「Manage Templates(Template Editor)」機能でテンプレート開発サイクルを速くする

Backstage PlatformEngineering Platform Engineering

はじめに

あけましておめでとうございます。ACS事業部の青木です。
2026年もよろしくお願いします。

私たちACS事業部では、Platform Engineering 推進の一環として、内部開発者ポータル（IDP: Internal Developer Portal）の整備に取り組んでいます。その際に中核となる仕組みの1つが、BackstageのSoftware Templates（Scaffolder）です。

Software Templatesは「新規プロジェクトやコンポーネントの立ち上げ」を標準化し、入力フォーム → 生成 → リポジトリ作成 → カタログ登録までを自動化できます。
このテンプレートですが、作るときに最初は「フォームがどう出るか」「アクションがどう動くか」を試行錯誤しながら作っていく必要があります。
そこで今回は、テンプレート作成・改修の反復を効率化するための機能として、Backstageに組み込まれている「Manage Templates(Template Editor)」機能をご紹介します。

前提条件 / 対象読者

  • Backstageをすでに導入済み、もしくはPoCで触り始めている方
  • Software Templates（Scaffolder）が扱う概念（テンプレート定義、steps、actions）をこれから学んでいきたい方
  • Software Templates（Scaffolder）を作っているが、作るのがなかなか面倒だなと感じている方

技術的背景：Software Templates（Scaffolder）の最小理解

まず、Software Templateについて整理してみましょう。
Software Templateを作るためにはtemplate.yamlの実装が必要ですが、template.yamlの内容は以下の要素で構成されています。

  • Software Templateリソースを定義する基本パラメータ: apiVersion: scaffolder.backstage.io/v1beta3 / kind: Template のYAMLで定義される
  • spec.parameters: フロントエンド（Scaffolder UI）に表示される入力フォーム（JSON Schema + ui:*拡張）
    • spec.steps: バックエンドで順番に実行される処理。各stepは action とその input を持つ
    • Action（Scaffolder action）: fetch:template や publish:github のような、テンプレート実行の部品。標準（built-in）もあれば、カスタムアクションも追加できる
    • Custom Field Extension: ui:field で呼び出せる、入力フォーム用の拡張（Reactコンポーネント + バリデーション）。Backstageが提供するもの（例: RepoUrlPicker / OwnerPicker）に加え、独自実装も可能
  • spec.output: テンプレートによってリソースを作成した後に、Backstageの画面に払い出されるリンクやメッセージ

template.yamlの例についてはこちらをご覧ください。

github.com

さて、見てお分かりの通り、テンプレート開発が難しく感じるポイントは、「同じYAMLファイル内で定義されるのに、実行場所が違う」点です。

  • spec.parameters はフロントエンドのフォーム表示と入力検証に影響
  • spec.steps はバックエンドの処理（外部API呼び出しやファイル生成など）に影響

このギャップを埋めるのが、今回紹介するManage Templatesです。

Manage Templates：フロントエンドの即時チェックが可能な開発UI

Backstage公式ドキュメント（Writing Templatesの「Template Editor」）では、テンプレート作成は反復的（iterative）になりやすく、テンプレートを実環境でテストするために Template Editor が用意されていると説明されています。

backstage.io

Manage TemplatesはそのTemplate Editorの機能をまとめたタイトルとして用意されており、内容はこれまでのTemplate Editorに近いものです。

画面を見てみるとわかる通り、4つの機能が提供されています。

  • Load Template Directory
  • Create New Template
  • Template Form Playground
  • Custom Field Explorer

どこから開ける？

Backstageのホーム画面から、[Create]→[画面右上の三点ボタン]→[Manage Templates]で開くことが可能です。

(https://<BackstageインスタンスのURL>>/create/editでも開くことができます。)

一般開放されているBackstage公式のデモ環境もありますので、すぐに触れるインスタンスをお持ちでない方はこちらからアクセスして確認してみましょう。

demo.backstage.io

Manage Templatesの各機能

機能としては4つあるものの、実質3種類の機能となっています。

  1. Load Template Directory/Create New Template

    • ローカルのテンプレートディレクトリ（template.yaml とスケルトンを含む）を読み込み、編集しながらフォームをプレビューできる

    • Create を押すと dry-run として実行され、結果（生成ファイルの内容など）と、各アクションのログを確認できる

    • ※注意点※：日本語で書かれているところは文字化けしてしまうため、そこはGitHub Repository側で確認が必要

      backstage.io

  2. Template Form Playground

    • Backstageに登録されている既存テンプレートを選び、template.yamlの書き方を確認したり、フォームを一時的に編集して挙動を確認できる

    • ただし ここでの変更はテンプレートに保存されない（検証用）

  3. Custom Field Explorer

    • インスタンスにロードされているCustom Field Extensionを選び、ui:options などを変えながらプレビューできる
      backstage.io

Manage Templates機能を利用する場面

Software Template開発時にManage Templates機能を利用することで、以下のような様々な場面で恩恵が得られると感じました。

  • Template開発時：
    • spec.parameters の調整（必須項目、表示順、ui:options、Secret入力など）をしながら、すぐフォームを確認できる
    • spec.steps の組み合わせ（fetch → publish → register など）が期待通り動くか、dry-runでログを確認できる
  • Software Templateで利用するカスタムプラグイン開発時：
    • Custom Field Explorerを活用して、実装後にどのように使用できるか確認できる
  • オンボーディング時：
    • Software Templateの仕組みや各アクションについて、UIでわかりやすく学ぶことができる

特にLoad Template Directory + dry-run結果の確認 は、「YAMLを書いて→git pushして→Backstageでテンプレ実行して…」というループを短縮できるなと思いました。

個人的な推しポイント：Skeleton内のGitHub Actionsワークフローファイルの変数のエスケープがやりやすい

また、個人的にうれしいと感じたポイントとして、「Skeletonディレクトリ内のGitHub Actionsワークフローファイルにvalues変数を使用する場合に、GitHub Actions用の変数のエスケープ処理がやりやすい」という点です。

テンプレート利用者に入力させた固有の値をテンプレートで利用する際場合には、spec.stepsにてfetch:templateアクションを利用します。

このとき、skeleton配下のコードに利用者が入力した値を${{ values.変数名 }}を使用することによって置換させることができますが、GitHub Actionsでも${{ }}の形式で変数を使用するため、GitHub Actions用の変数までレンダリングしてしまいます。

GitHub Actionsに値の置換を一切利用しないのであればfetch:templateのcopyWithoutRenderオプションに.githubディレクトリを指定することでレンダリングを回避できますが、利用したい場合は以下のようにBackstageの変数を記載した後にGitHub Actions用の変数をエスケープする必要があります。

working-directory: ${{ env.TF_WORKING_DIR_TERRAFORM }}
#↓GitHub Actions実行時に正常に動作するようにエスケープ#
working-directory: ${{ '${{ env.TF_WORKING_DIR_TERRAFORM }}' }}

この作業、VSCode内で実施すると見栄えがあまりよくなくわかりづらいのですが、Template Editorだと非常に見やすく作業ができます。

VSCodeで見た場合：

Template Editorで見た場合：

おわりに

Software Templates（Scaffolder）は、プロジェクト立ち上げを標準化できる一方で、テンプレートそのものの開発は「フォーム（spec.parameters）と処理（spec.steps）を行ったり来たり」しがちです。今回紹介したManage Templatesは、この反復をUI上で短縮し、テンプレート開発の体験をかなり良くしてくれます。

特に効果が大きいのは次の2点です。

  • Template Form Playgroundでフォームの調整を即時確認できる（JSON Schema / ui:field / ui:options の試行錯誤が速い）
  • Load Template Directoryのdry-runで、生成結果とログをまとめて確認できる（YAMLを直してPushして…のループを減らせる）

また、Custom Field Explorerがあることで、テンプレートを書く側だけでなく「フォーム拡張（Custom Field Extension）を作る側」も、ui:options の組み合わせや見た目の確認を自己完結できます。テンプレートやプラグインの開発が属人化しやすい現場ほど、こうした“試せる場”があるだけでかなり助かると思います。

もしBackstageをすでに運用しているなら、まずは1つテンプレートを選び、Manage Templates上で「フォーム調整 → dry-runでログ確認」までを通してみてください。テンプレート開発のボトルネックがどこにあるのかが、かなりクリアになります。

本ブログは以上になります。ここまでお読みいただきありがとうございました。

ACS事業部のご紹介

私達ACS事業部はクラウドネイティブ技術、Azure AI サービス、Platform Engineering、AI駆動開発支援などを通して、攻めのDX成功に向けた開発者体験・開発生産性の向上・内製化のご支援をしております。

www.ap-com.co.jp また、一緒に働いていただける仲間も募集中です！
今年もまだまだ組織規模拡大中なので、ご興味持っていただけましたらぜひお声がけください。 www.ap-com.co.jp

本記事の投稿者
青木平：ウイスキーと柔道が好きなエンジニアです。
Kubestronaut/Microsoft Top Partner Engineer 2025