Backstageをマスターする: ソースコードへの地図、source-locationアノテーション完全ガイド

6月 26, 2026

—

こんにちは！今日は、Backstageのソフトウェアカタログを支える最も重要なメタデータの一つであるbackstage.io/source-locationアノテーションについて深く掘り下げていきます。🚀

Backstageを使用していると、サービスの詳細ページで「View Source」ボタンをクリックしたり、ドキュメントの場所をリンクしたりする際に、この設定によく出会います。この一行の設定がどのような魔法をかけ、なぜ重要なのかを完全に理解しましょう！💡

🏗️ backstage.io/source-locationとは何ですか？

Backstageで管理されるすべてのリソース（コンポーネント、API、リソースなど）は、エンティティ(Entity)と呼ばれるYAMLファイルで定義されます。このとき、backstage.io/source-locationアノテーションは、そのエンティティの実際のソースコードが保存されている物理的な場所を指し示す道標の役割を果たします。

簡単に言えば、「このサービスの本当の正体（ソースコード）は、あのGitHubリポジトリのこのフォルダにあるよ！」と教えてくれるのです。📍

🌟 なぜこのアノテーションが重要なのでしょうか？

単なるアドレス記録以上の意味を持ちます。このアノテーションが正しく設定されて初めて、Backstageの次の主要機能が動作します。

1. ソースコードへの直接リンク (View Source) 🔗

ユーザーがBackstage画面で「View Source」ボタンをクリックした際、GitHubやGitLabの該当リポジトリページへ即座に移動できるようにします。開発者がカタログを見ていて、実際のコードを修正したいときに、道を見つける最も速い通路となります。

2. TechDocs（ドキュメント化）の基盤 📖

Backstageの自慢であるTechDocsは、ソースコードと一緒に保存されたMarkdownファイルを読み込み、ウェブで表示します。このとき、source-locationはTechDocsビルドエンジンがどこからMarkdownファイルを取得すべきかを教える基準点となります。

3. スキャナーおよびプロセッサーのガイド 🕵️‍♂️

Backstageバックエンドは、定期的にソース位置を確認し、変更があるか、新しい設定が追加されたかをスキャンします。このアノテーションがないと、システムは該当エンティティが「生きているコード」なのか、単なる記録なのかを区別するのが難しくなります。

🛠️ 実践活用：どのように記述しますか？

アノテーションは通常、エンティティYAMLのmetadataセクションに配置されます。

📝 基本形式の例

YAML

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-awesome-service
  annotations:
    # ソースコードの場所を指定します。
    backstage.io/source-location: url:https://github.com/my-org/my-repo/tree/main/
spec:
  type: service
  owner: guest
  lifecycle: production

🔍 設定ルール (Prefix)

url: 接頭辞: 最も一般的に使用される方法で、ウェブ経由でアクセス可能なURLを入力します。
相対パス vs 絶対パス: 通常はリモートリポジトリの絶対アドレスを使用しますが、モノレポ環境では、該当サービスが位置する特定のサブフォルダまで指定することが推奨されます。

⚠️ 注意すべき点 (Common Mistakes)

ブランチの明示: mainやmasterのようなブランチ名がURLに含まれている必要があります。これにより、正確な位置を追跡できます。🚩
接頭辞の欠落: 単にhttps://…とだけ記述してはいけません。必ずurl:接頭辞を付けることで、Backstageが位置情報であることを認識します。
権限の問題: Backstageサーバーが該当位置（GitHubなど）にアクセスできるトークンや権限が設定されている必要があります。これにより、実際の機能を100%活用できます。🔐

🏁 結論：エンティティと現実世界を結ぶ架け橋

backstage.io/source-locationは、Backstageという仮想カタログと、開発者が毎日触れる実際のコードとをつなぐ最も強力な連結点です。この設定を細かく管理するだけで、チームメンバーの探索時間を画期的に短縮できます。

皆さんのエンティティファイルに、今すぐ正確な位置情報を付与してみてください！🚀