数クリックで完了！Backstageカタログ手動登録（Manual Register）完全ガイド

7月 1, 2026

—

プラットフォームエンジニアの皆さん、こんにちは！🛠️ 新しいマイクロサービスを作成したり、既存のプロジェクトをBackstageに統合したいとき、最も速く確実な方法は何でしょうか？

自動スキャン機能が設定されていなくても心配いりません。Backstageは、ユーザーがエンティティの場所を直接Backstageに伝える手動登録（Manual Registration）方式をサポートしています。それでは、その手順を一つずつ見ていきましょう！

1. 手動登録とは何ですか？ 🤔

手動登録とは、開発者が自身のサービス定義ファイル（catalog-info.yaml）がどこにあるかをBackstageに直接伝える行為です。

核心メカニズム： ファイルのURL（パス）を登録します。
サポートされるソース： GitHub、GitLab、Bitbucketなどのソースコードホスティングサービスにアップロードされたファイルの直接リンクを使用します。

2. 準備物：catalog-info.yaml 📄

手動登録を行う前に、必ずプロジェクトリポジトリに設定ファイルが存在する必要があります。このファイルがないと、Backstageは登録する情報を読み込むことができません。

# 例: catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-manual-service
  description: 수동으로 등록한 멋진 서비스입니다.
spec:
  type: service
  owner: user:guest
  lifecycle: experimental

このファイルをリポジトリ（例：GitHub）にPushした後、そのファイルのブラウザアドレスバーのURLをコピーしておきましょう！🔗

3. 段階別手動登録手順 (Step-by-Step) 🚶‍♂️

それでは、実際のBackstage画面で登録してみましょう。

ステップ1：Catalogメニューにアクセス

左側のサイドバーから[Catalog]メニューをクリックします。

ステップ2：「Create」または「Register」ボタンをクリック

カタログメイン画面の右上にある[Create]ボタンを押します。通常、ここは新しいソフトウェアテンプレートを作成する場所ですが、手動登録ボタンも一緒に配置されています。

ステップ3：「Register Existing Component」を選択

画面の隅にある[Register Existing Component]ボタンを見つけてクリックします。これこそが私たちが探している手動登録機能です！✨

ステップ4：URL入力と分析

コピーしておいたcatalog-info.yamlファイルのURLを入力欄に貼り付けます。

Analyze： ボタンを押すと、Backstageがそのパスにファイルがあるか、文法が正しいかなどを事前に検査します。

ステップ5：最終確認と完了

検査が通過したら[Import]をクリックします。これで、カタログリストに今登録したサービスを確認できます！🎉

4. 手動登録の利点と注意事項 💡

利点 👍

即時性： 自動収集（Ingestion）サイクルを待つ必要なく、即座に反映されます。
柔軟性： 特定のプロジェクトのみを選択的にカタログに表示したい場合に便利です。
テスト容易性： 新しいcatalog-info.yaml設定をテストする際に最も速い方法です。

注意事項 ⚠️

URL権限： Backstageバックエンドが該当URL（例：Private Repo）にアクセスできる権限（Token）が設定されている必要があります。
重複登録： 既に登録されているURLを再度登録しようとするとエラーが発生する可能性があります。

5. 要約：手動登録の核心3行まとめ 📝

準備： プロジェクトリポジトリにcatalog-info.yamlファイルをプッシュする。
コピー： そのファイルのオリジナル（Raw）URLまたはブラウザアドレスをコピーする。
登録： Backstage UIのRegister Existing ComponentメニューでURLを入力し、インポートする。

🏁 終わりに

Backstageカタログに自分の足跡を残す最も直接的な方法である「手動登録」について学びました。最初は手動で登録して感覚を掴み、後でサービスが増えたらEntity Providersを通じた自動収集に拡張していくのが良いでしょう。🚀