creating-backstage-scaffolder-action

Backstage Scaffolder アクションの作成

このスキルを使用する場面

• Scaffolder テンプレートから呼び出せるカスタムアクションを作成する場合（例：acme:user:create、myorg:slack:notify）
• 既存の scaffolder-backend-module-* プラグインを編集する場合

作成するもの

Scaffolder アクションは、scaffolderActionsExtensionPoint に対して TemplateAction を登録するバックエンドモジュール（createBackendModule({ pluginId: 'scaffolder', ... })）です。構成要素は次の2つです。

1. アクション本体（createTemplateAction で作成）
2. アクションを登録するモジュール

適切なパターンを選ぶ

作成するもの	リファレンス
アクション本体	references/template-action.md
アクションを組み込むモジュール	references/module-registration.md

2つの呼び出し方法

• 単独：既存の scaffolder-backend-module-* を編集します。
• スキャフォールド後（creating-backstage-plugin から scaffolder-backend-module 用に呼び出される場合）：アクション定義とモジュール登録の両方のファイルをまとめて生成します。

よくある注意点

• アクションの id は <namespace>:<name>（または <namespace>:<group>:<name>）の規則に従います。namespace は自由に選べます。インストール済みモジュールのカタログにある他のアクションと衝突しない、安定した名前を選んでください。
• スキーマは生の Zod スキーマではなく、ファクトリー関数です。例：input: { name: z => z.string() }（input: { name: z.string() } ではありません）。Backstage は Zod のバージョンを内部で固定するためにこのパターンを使用します。../backstage/plugins/scaffolder-node/src/actions/createTemplateAction.ts を参照して形式を確認してください。
• アクションハンドラーのコンテキスト（ctx）には、ctx.logger、ctx.workspacePath、ctx.input（入力スキーマに基づく型付き）、出力を出力する ctx.output(name, value)、ユーザー ID を取得する ctx.getInitiatorCredentials()、サンドボックス化された作業用の ctx.createTemporaryDirectory()、キャンセル用の ctx.signal（AbortSignal）、ドライランモード用の ctx.isDryRun が含まれます。
• 実行時間の長いアクションでは、定期的に ctx.logger.info を呼び出してください。Scaffolder の UI はログをユーザーにストリーミングします。
• ドライランに対応するには、supportsDryRun: true を設定し、ハンドラー内で ctx.isDryRun を確認して副作用をスキップしてください。
• テンプレートでは if: ${{ always() }} と if: ${{ failure() }} を使って、失敗後のステップ実行を制御できます。always() は無条件に実行し、failure() は先行するステップが失敗した場合にのみ実行します。これらはテンプレートエンジンに組み込まれているため、アクションの作成者が対応する必要はありません。