内部開発者プラットフォーム（IDP）向けWebアプリの作り方

作るものの全体像：平易に説明するIDP Webアプリ

IDPのWebアプリは、エンジニアリングシステムへの社内の“玄関”です。ここで開発者は既存の資産（サービス、ライブラリ、環境）を発見し、ソフトウェアを構築・運用するための推奨ルートに従い、複数のツールを探し回らずに変更を要求できます。

同時に重要なのは、Git、CI、クラウドコンソール、チケッティングの代替となる“全部入り”を目指すべきではないという点です。目標は既に使っているものをオーケストレーションして摩擦を減らすこと——正しい道を最も簡単にすることです。

解決すべき問題

多くのチームがIDP Webアプリを作るのは、日常業務が次のような理由で遅くなるからです：

• ツールの拡散：どこをクリックすべきかという知識が部族的記憶にある。
• オンボーディングの遅さ：新人がプロセスを学ぶのに数週間かかり、出荷より学習に時間を費やす。
• 基準の不一致：サービスがばらばらに作られ運用されるため、信頼性やセキュリティが難しくなる。

Webアプリはこれらを反復可能なワークフローと明確で検索可能な情報に変えるべきです。

コアビルディングブロック

実用的なIDP Webアプリは通常、三つの部分から成ります：

1. ポータルUI：サービスカタログ、ドキュメントへの入口、セルフサービフォーム（例：「サービスを作る」「アクセスを要求する」「データベースをプロビジョニングする」）。
2. バックエンドAPI：リクエストを検証し、ポリシーを適用し、アクションを記録するビジネスロジック。
3. 統合：アクションが実際の記録システムで起こるようにツールチェーン（Gitホスティング、CI/CD、インフラツール、シークレット、インシデント管理）へのコネクタ。

誰が所有するか（誰が所有しないか）

プラットフォームチームは通常ポータル製品を所有します：エクスペリエンス、API、テンプレート、ガードレール。

プロダクトチームは自分たちのサービスを所有します：メタデータの正確性、ドキュメント/ランブックの維持、提供されたテンプレートの採用。健全なモデルは共有責任です：プラットフォームチームが舗装された道を作り、プロダクトチームがその道を走って改善に協力します。

ユーザー、ユースケース、成功指標

IDP Webアプリは、誰にどのような“ハッピーパス”を提供するかで成功が決まります。ツール選定やアーキテクチャ図を引く前に、誰がポータルを使い、何を達成したいのか、進捗をどう測るかを明確にしてください。

主なユーザー（関心事）

ほとんどのIDPポータルには四つの主要なオーディエンスがあります：

• アプリケーション開発者：チケットを待たずにサービスを作って安全に動かせる、速く安全なデフォルトが欲しい。
• SRE / 運用：標準化、予測不可能な変更の減少、インシデント時の明確な所有権を望む。
• セキュリティ / コンプライアンス：アクセスレビュー、シークレット取り扱い、監査トレイルなどの一貫したコントロールを、配信を阻害せずに求める。
• エンジニアリングマネージャ / プロダクトリード：何があるか、誰が所有しているか、チームが信頼して出荷しているかの可視性を求める。

各グループが一文でどう得をするか説明できなければ、ポータルは任意の存在に感じられるでしょう。

5～10の主要ジャーニーをマップする

週に発生する（年単位でない）ジャーニーを選び、真にエンドツーエンドにします：

• テンプレートから新しいサービスを作る（リポジトリ + CI + 所有権 + タグ）。
• 環境を要求する（dev/stage）ガードレール付き。
• サービスヘルスを見る（デプロイ状況、アラート、依存関係）。
• キー/シークレットをローテートする（監査可能なワークフロー）。
• システムやデータセットへのアクセスを要求する（承認つき）。

各ジャーニーは「トリガー → ステップ → タッチされるシステム → 期待される結果 → フェイラーモード」として書いてください。これはプロダクトバックログであり受け入れ基準になります。

実際に追える成功指標を定義する

良い指標は時間短縮と摩擦の削減に直結します：

• 新しいサービスのTime-to-first-deploy（中央値、p90）
• よくあるリクエストの手動チケット量（と解決時間）
• 採用率：登録済みサービスの割合、テンプレートを使うチームの割合
• ポータルがデリバリを標準化した場合の変更失敗率と平均復旧時間（MTTR）

“バージョン1”のスコープ声明を書く

短く見える場所に置いてください：

V1 スコープ: 「承認済みテンプレートから開発者がサービスを作成し、サービスカタログにオーナーと登録し、デプロイ＋ヘルス状況を表示するポータル。基本的なRBACと監査ログを含む。カスタムダッシュボード、完全なCMDB置き換え、オーダーメイドワークフローは除外。」

この声明は機能拡張のフィルターでありロードマップのアンカーになります。

内部ポータルのMVPスコープとロードマップ

内部ポータルは一つの痛みをエンドツーエンドで解決し、それから拡張することで成功します。最短経路は、数四半期ではなく数週間で実際のチームに出す狭いMVPです。

「完結感」のある狭いMVP

三つのビルディングブロックから始めます：

• サービスカタログ：何があるか、誰が所有しているか、運用リンクがどこにあるかを一箇所で見られる。
• 一つのセルフサービスワークフロー：高頻度なリクエスト（例：「新しいサービスリポを作る」「標準環境をプロビジョニングする」）を自動化。
• ドキュメント/リンクハブ：すべてを移行せずに既存のソース（CI/CD、インシデントツール、ランブック）へのリンクを貼って、実際に使われるものを学ぶ。

このMVPは小さいが明確な成果を出します：「サービスを見つけて、Slackで聞かずに重要な1つのアクションを実行できる」。

プロトタイプのUXとワークフローを素早く検証したい場合、Koder.aiのようなvibe-codingプラットフォームは、記述されたワークフロースペックからReactベースのWebアプリとGo + PostgreSQLバックエンドを生成し、ソースコードのエクスポートをサポートするため、チームが素早く反復しつつコードベースの長期所有権を保てるので有用です。

バックログ構造：発見、作成、運用、ガバナンス

ロードマップを整理するために作業を四つのバケットに分けます：

• Discover（発見）：検索、タグ、所有権、チームページ、依存関係のビュー。
• Create（作成）：テンプレート、スキャフォールディング、環境プロビジョニング、標準設定。
• Operate（運用）：ダッシュボード/ランブックへのリンク、オンコール情報、SLOサマリ、共通アクション。
• Govern（ガバナンス）：RBAC、承認ステップ、監査ログ、ポリシーチェック。

この構造により「カタログだけ」あるいは「自動化だけ」で何もつながらないポータルを防げます。

今自動化すべきか、外部リンクにとどめるか

自動化は少なくとも以下の基準のいずれかを満たす場合にのみ行ってください：(1) 週次で繰り返される、(2) 手動だとエラーを起こしやすい、(3) マルチチームの調整が必要。その他は適切なツールへのキュレーションされたリンクと明確な指示・所有権で十分です。

改装なしで順次強化する

ポータルを設計する際、新しいワークフローがサービスや環境ページの追加「アクション」として差し込めるようにします。新しいワークフローごとにナビゲーションの再設計が必要だと採用が停滞します。ワークフローをモジュールとして扱い、入力・ステータス・履歴を一貫させることで、精神モデルを変えずに追加できます。

参照アーキテクチャ：UI、API、統合

実用的なIDPポータルアーキテクチャは、ユーザー体験をシンプルに保ちながら、裏側で“面倒な”統合作業を確実に処理します。目標は開発者に一つのWebアプリを提供することですが、実際にはアクションがGit、CI/CD、クラウドアカウント、チケッティング、Kubernetesに跨ります。

デプロイモデルを選ぶ

三つの一般的パターンがあり、どれが適切かはどれだけ速く出すかと何チームが拡張するかによります：

• 単一アプリ（モノリス）：MVPが最速。UI、API、統合ロジックが一緒にデプロイされる。プラットフォームチームがほとんどの機能を所有する場合に良い。
• モジュラーサービス：UI、コアAPI、いくつかの統合サービスを分離。スケールしやすく、成長時の所有権が明確。
• プラグインベース：安定した“コア”にカタログソース、スキャフォールディング、ドキュメント、ワークフローのプラグイン。多数のチームが機能を提供する場合に最適。

コアコンポーネント（どこで動くか）

最低限想定するビルディングブロック：

• Web UI（開発者ポータル）：カタログ閲覧、ゴールデンパス、フォーム、ステータスページ。
• バックエンドAPI（多くはAPIゲートウェイの背後）：認証、RBACチェック、検証、オーケストレーション。
• 統合ワーカー：リポジトリ作成、環境プロビジョニング、CI設定などの長時間タスクを非同期で実行。
• データベース：ポータル設定、キャッシュされたカタログビュー、ワークフローヒストリ、監査イベント。

状態はどこに置くべきか

ポータルが“所有する”ものと単に“表示する”ものを早期に決めてください：

• ソースオブトゥルースは既存のシステムに置く（Git、クラウドIAM、CI/CD、Kubernetes、チケッティング）。
• ポータルDBに保存するもの：ワークフローリクエスト、ステータス、承認、監査ログ、UIを高速にするためのキャッシュインデックス。

統合の信頼性

統合は通常の理由で失敗します（レート制限、短時間の障害、部分成功）。次を設計で考慮してください：

• バックオフつきリトライと明確なエラーメッセージ
• 冪等性（リクエストを再実行しても重複を作らない）
• タイムアウトとキャンセル
• 永続的なワークフローヒストリでユーザーが何が起きたか見て安全に回復できる

データモデル：サービスカタログと所有権

サービスカタログは、何があるか、誰が所有しているか、システムの中でどのように位置付けられるかの真の情報源です。明確なデータモデルは“謎のサービス”や重複エントリ、壊れた自動化を防ぎます。

コアの「Service」エンティティを定義する

組織で「サービス」が何を意味するか合意してください。多くのチームではデプロイ可能な単位（API、ワーカー、ウェブサイト）でライフサイクルがあります。

最低限モデル化するフィールド：

• Name + description（人間向け表示）
• Owners：プライマリチームとオプションの二次連絡先（オンコールグループ、テックリード）
• Source repositories：1つまたは複数のリポリンク/ID
• Runtime environments：dev/stage/prod、あるいはリージョン固有バリアント
• Dependencies：上流/下流サービスや共有ライブラリ

ポータルを支える実践的メタデータを追加：

• Lifecycle（experimental, active, deprecated）
• Criticality/tier（サポート期待値とガバナンスポリシー用）
• Links（ランブック、ダッシュボード、SLO、インシデントチャネル）

関係を明示的にモデル化する

関係をテキストフィールドだけにせずファーストクラスに扱ってください：

• Services ↔ teams：チームごとに多くのサービス；共有所有もある（primary_owner_team_id と additional_owner_team_ids を使う）
• Services ↔ resources：Kubernetesのネームスペース、キュー、データベースなどクラウドリソースへ接続して「このサービスは何を使っている？」に答えられるようにする
• Service tiers：ティアを構造化enumとして保存し、ポリシーに紐づける（例：tier-0はオンコールと監査ログ必須）

このリレーショナル構造で「Team Xが所有するすべて」や「このデータベースに触るすべてのサービス」のようなページを作れます。

識別子と命名ルール

重複が発生しないよう正準IDを早めに決めてください。一般的なパターン：

• 安定したスラッグ（例：payments-api）をユニークに強制
• 不変のUUIDと人に優しいスラッグを併用
• 任意：リポ由来キー（github_org/repo）を使う場合、リポとサービスが1:1の組織で有効

許可文字、ユニーク性、リネームポリシーを文書化し、作成時に検証してください。

データの鮮度維持計画

カタログが陳腐化すると失敗します。次の方法を一つまたは組み合わせて選んでください：

• スケジュールされたインポート（Git、CI/CD、クラウドインベントリからの夜間同期）
• Webhooks（リポ変更、デプロイで更新）
• イベントストリーム（service.createdやdependency.updatedのようなイベントを公開）

各レコードにlast_seen_atとdata_sourceフィールドを保持して鮮度を表示し、競合のデバッグを容易にします。

認証、認可、監査可能性

信頼されるIDPポータルにするには、認証（あなたは誰か？）、認可（何ができるか？）、監査可能性（何が起き、誰がやったか？）の三つが連携して働く必要があります。早期にこれらを正しく設計すれば、ポータルが本番変更を扱い始めたときの手戻りを避けられます。

グループマッピングを伴うSSOをデフォルトにする

多くの企業は既にアイデンティティ基盤を持っています。使いましょう。

OIDCやSAMLによるSSOをデフォルトサインインパスにして、IdP（Okta、Azure AD、Google Workspace等）からグループメンバーシップを取得し、ポータルのロールやチームメンバーシップにマップします。

これによりオンボーディングが簡単になり（ログインすれば適切なチームに入る）、パスワード管理を避け、ITがMFAやセッションタイムアウト等のグローバルポリシーを強制できます。

明確なロール定義（と各ロールの権限）

「admin vs everyone」の曖昧なモデルは避けてください。実用的なロールの例：

• Developer：ポータルの閲覧、テンプレートとセルフサービスワークフローを許可されたスコープ内で使用。
• Service Owner：サービスカタログエントリの管理（メタデータ、オンコール、ライフサイクル）、サービス専用の履歴参照。
• Approver：機微なリクエスト（本番アクセス、新環境、コスト影響のあるリソース）を承認/拒否。
• Platform Admin：テンプレート、統合、グローバル設定、ポリシーデフォルトの管理。
• Auditor：監査ログ、承認、構成履歴への読み取り専用アクセス。

ロールは小さく分かりやすく保ってください。混乱したモデルは採用を下げます。必要なら後から拡張できます。

RBACに加えてリソースレベルの権限を

RBACは必要ですが十分ではありません。ポータルはチーム、サービス、環境といったリソース単位の権限も必要です。

例：

• 開発者は自分のチームのサービスに対して「サンドボックス環境作成」ワークフローを起動できるが他チームにはできない。
• サービスオーナーは自分が所有するサービスのカタログエントリを編集できる。
• 承認者は特定のコストセンターや本番ネームスペースに対するリクエストのみ承認できる。

これを実装する単純なポリシーパターンは：(principal) can (action) on (resource) if (condition)。最初はチーム/サービスのスコーピングから始めて拡張してください。

機微な操作のための監査トレイル

監査ログをバックエンドの詳細事項として扱わず、ファーストクラス機能にしてください。ポータルは次を記録すべきです：

• 誰がセルフサービスワークフローを開始したか（発生場所含む）
• 提出されたパラメータ値（シークレットはマスク）
• 誰が承認/拒否したかとコメント
• 結果としての変更（CI/CD実行へのリンク、チケット、インフラ変更）
• テンプレート、権限、統合の変更

監査トレイルはサービスページ、ワークフローの「履歴」タブ、コンプライアンス向けの管理ビューから容易に参照可能にしてください。インシデントレビューの迅速化にも寄与します。

開発者向けUX設計：正しい道を簡単にする

良いIDPポータルUXは派手さではなく、誰かが出荷しようとするときの摩擦を減らすことです。開発者は次の三つに素早く答えられるべきです：何があるか？何を作れるか？今何が注意を要するか？

実際のタスクに基づくナビゲーション設計

バックエンドシステム別（「Kubernetes」「Jira」「Terraform」）ではなく、開発者が実際に行う作業に基づいてメニューを構成してください：

• Discover：サービス、API、ドキュメント、所有者、ランブックを見つける
• Create：新しいサービスを開始する、エンドポイントを追加する、データベースを要求する
• Operate：ヘルス、インシデント、デプロイ状況、最近の変更を見る
• Govern：権限、コンプライアンスチェック、ポリシー例外

このタスクベースのナビゲーションはオンボーディングも容易にします：新メンバーはツールチェーンを知らなくても始められます。

所有権を見逃せない場所に置く

すべてのサービスページは次を明示的に表示すべきです：

• 所有チームとチームチャネル
• オンコールローテーションとエスカレーション経路
• プライマリリポジトリとデプロイターゲット

この「誰が所有？」パネルはタブの奥ではなく上部に置いてください。インシデント時は秒が重要です。

人が考える方法に合う検索、フィルタ、ステータス

高速検索がポータルの力になります。チーム、ライフサイクル（experimental/production）、ティア、言語、プラットフォーム、「自分が所有」など、自然に使うフィルタをサポートしてください。健康/劣化、SLO危険、承認待ちなどの明確なステータスインジケータを付けて、ユーザーが一覧をスキャンして判断できるようにします。

テンプレートと妥当なデフォルトでフォームを短く保つ

リソース作成時は今本当に必要なことだけを聞いてください。テンプレート（ゴールデンパス）とデフォルトで避けられるミスを防ぎます——命名規則、ログ/メトリクスのフック、標準CI設定は事前入力されるべきで再入力させないでください。オプションフィールドは「詳細オプション」の下に隠し、ハッピーパスを速く保ちます。

セルフサービスワークフロー：テンプレート、承認、履歴

セルフサービスはIDPが信頼を得る場所です：開発者が一般的なタスクをチケットを開かずに完了できる一方で、プラットフォームチームは安全性、コンプライアンス、コスト管理を維持できます。

まず重要なワークフロー種別を選ぶ

頻度が高く摩擦が大きい少数のワークフローから始めます。典型的な「最初の四つ」：

• サービス作成：リポのスキャフォールディング、サービスカタログ登録、所有権設定、CI/CDのブートストラップ。
• 環境プロビジョニング：標準のネットワーク、ログ、予算を備えたdev/staging環境の作成。
• アクセス要求：最小権限でシステム（DB、キュー、サードパーティAPI）へのアクセスを付与し、有効期限を設定。
• シークレットローテーション：ローテーションをトリガーし、ダウンストリーム構成を更新し、アプリケーションが正常か検証。

これらは意見を持った（opinionated）ワークフローで、ゴールデンパスを反映しつつも制御された選択肢（言語/ランタイム、リージョン、ティア、データ分類）を許容します。

ワークフロー契約を定義する（テンプレートの予測可能性のため）

すべてのワークフローをプロダクトのAPIのように扱ってください。明確な契約でワークフローは再利用可能、テスト可能、ツールチェーンと統合しやすくなります。

実用的な契約には次が含まれます：

• Inputs：型付きフィールドとデフォルト（例：service name、owner team、environment、data sensitivity）。
• Validation：命名ルール、許可リージョン、クォータチェック、「既に存在するか？」チェック。
• Steps：テンプレート実行、CI/CD呼び出し、クラウドリソース作成、サービスカタログ更新などのアクション列。
• Outputs：開発者が必要とする成果物とリンク（リポURL、デプロイURL、ランブックリンク、作成されたリソース）。

UXは開発者が実際に決定できる入力だけを表示し、残りはサービスカタログとポリシーから推論するように保ってください。

迅速で明確かつ強制可能な承認

承認は避けられない場合があります（本番アクセス、敏感データ、コスト増加）。ポータルは承認を予測可能にするべきです：

• 誰が何を承認するか：承認者をルールベースで定義（チームオーナー、システムオーナー、セキュリティ）し、アドホックな個別通知を避ける。
• 時間制限：承認のSLAを設定し、古いリクエストは自動失効させる。
• エスカレーション：主承認者が不在の場合はバックアップグループやオンコールへルーティング。

重要なのは承認がワークフローエンジンの一部であり、手動の副次チャネルでないことです。開発者はステータス、次のステップ、なぜ承認が必要かを見られるべきです。

チームが自己デバッグできるよう履歴と結果を保存

すべてのワークフロー実行は恒久的な記録を生成すべきです：

• 使用された入力、検証結果、承認者の決定
• ステップごとのログ（シークレットはマスク）
• 最終成果物、作成されたリソース、ロールバックアクション

この履歴が“紙の跡”となりサポート手段になります：失敗したときにどこでなぜ起きたかを見て多くはチケットを切らずに解決できます。プラットフォームチームはこのデータでテンプレート改善や繰り返す障害の検出ができます。

統合：ポータルをツールチェーンに接続する

ポータルが「実用的」に感じられるのは、開発者が既に使っているシステムを読み書きできるときです。統合はカタログエントリをデプロイ可能、監視可能、サポート可能なものに変えます。

明確な統合チェックリストから始める

ほとんどのポータルは次の基礎接続を必要とします：

• Git（リポジトリ、デフォルトブランチ、CODEOWNERS、プルリク）
• CI/CD（パイプライン、ビルド状況、アーティファクト、プロモーション）
• Kubernetes（クラスター、ネームスペース、ワークロード、ロールアウト）
• Cloud（アカウント/プロジェクト、ネットワーキング、マネージドサービス）
• IAM（チーム、グループ、SSO、ロールマッピング）
• Secrets（Vault、シークレット参照、ローテーション状況）

どのデータが読み取り専用（例：パイプライン状況）でどの操作が書き込み（例：デプロイのトリガー）かを明示的にしてください。

APIファーストを優先；必要ならWebhooksや同期を使う

APIファースト統合は認可やスキーマ、エラーハンドリングを検証しやすくテストもしやすいです。

Webhooksは近リアルタイムのイベント（PRマージ、パイプライン完了）向けに使い、定期同期はイベントをプッシュできないシステムや最終的整合性が受け入れられる場合に使います（例：クラウドアカウントの夜間インポート）。

コアにベンダーを埋め込まないコネクタ層を作る

ベンダー特有の詳細を安定した内部契約（例：Repository、PipelineRun、Cluster）に正規化する薄い“コネクタ”または“統合サービス”を作ってください。これでツールを移行する際の変更を隔離し、ポータルのUI/APIをクリーンに保てます。

実践パターン：

• ポータルがコネクタを呼ぶ
• コネクタが認証、レート制限、リトライ、マッピングを扱う
• コネクタが正規化されたデータと実行可能なリンク（例：/deployments/123）を返す

障害モードとユーザーがすべきことを文書化する

各統合には小さなランブックを用意してください：劣化がどう見えるか、UIでどう表示するか、ユーザーは何をすべきか。

例：

• Git APIがレート制限された場合： ポータルはキャッシュされたリポデータを表示；「テンプレートから作成」は無効化される。
• CI/CDがダウンした場合： 手動フォールバック（パイプラインUIへのリンク）を提示し、リトライのタイミングを説明。
• シークレットマネージャが利用不可のとき： 新しいシークレットを要する変更をブロック；サービスメタデータの読み取りは許可。

これらのドキュメントをプロダクト近傍（例：/docs/integrations）に置き、開発者が推測しなくて済むようにしてください。

可観測性：ポータルと自動化の監視

IDPポータルは単なるUIではなく、CI/CDジョブのトリガー、クラウドリソースの作成、サービスカタログの更新、承認の強制を行うオーケストレーション層です。可観測性により「何が起きた？」「どこで失敗した？」「次に誰が動くべき？」に迅速かつ自信を持って答えられます。

ステップを跨いだリクエストの追跡

各ワークフロー実行に相関IDを付与し、ポータルUIからバックエンドAPI、承認チェック、外部ツール（Git、CI、クラウド、チケッティング）まで追跡できるようにします。リクエストトレースを加えて、各ステップの経路と時間を一望できるようにします。

トレースに加えて、構造化ログ（JSON）を使い、workflow name、run ID、step name、target service、environment、actor、outcomeなどを含めてください。これにより「deploy-templateの失敗が多い実行」「Service Xに影響するすべて」をフィルタできます。

開発者の痛みに即したメトリクス

基本的なインフラメトリクスだけでは不十分です。ワークフローに紐づくメトリクスを追加してください：

• ワークフロー/ステップごとの実行回数、成功率、所要時間
• 承認待ち時間と実行時間（ボトルネックの特定に有用）
• コネクタからのリトライ、タイムアウト、レート制限

ポータル内の運用ビュー

プラットフォームチーム向けに“一目でわかる”ページを用意してください：

• ワークフローキュー：実行中、キュー中、失敗、承認待ち
• コネクタヘルス：トークン有効性、最終成功呼び出し、エラーレート
• 同期状況：最後のカタログ同期、検出されたドリフト、バックログサイズ

各ステータスはドリルダウンと該当実行の正確なログ/トレースへのリンクを持たせてください。

アラート、保持、監査

壊れた統合（連続する401/403）、承認が滞っている（N時間アクションなし）、同期失敗などにアラートを設定してください。データ保持も計画し、高ボリュームログは短めに保持しつつ、監査イベントはコンプライアンスと調査のために長めに保持し、アクセス制御とエクスポートオプションを設けます。

セキュリティとガバナンス：チームを遅らせずに守る

IDPポータルのセキュリティは“ゲート”ではなく“ガードレール”として機能するのが理想です。安全な道を最も簡単にすることで危険な選択を減らし、チームの自律性を保ちます。

入力を検証し標準を自動適用する

多くのガバナンスは開発者が何かを要求する瞬間に行えます（新サービス、リポ、環境、クラウドリソース）。すべてのフォームとAPI呼び出しを信頼しない入力として扱ってください。

コードで標準を強制し、ドキュメントだけに頼らないでください：

• 所有（チーム、オンコール、エスカレーション連絡）を必須にし、欠けていれば作成をブロック。
• 命名規則（サービス名、リポ名、環境）を検証して衝突と混乱を避ける。
• コスト配分や発見のためのタグ/メタデータを必須にする。
• 最低限のポリシーを満たさないリクエストは拒否（例：「公開露出」は追加レビューが必要）。

これによりサービスカタログがきれいに保たれ、監査が格段に楽になります。

シークレットを設計上保護する

ポータルは認証トークンやクラウドキーなどの資格情報に触れることがあります。シークレットは扱いを厳しくしてください：

• シークレットをログに出力したりエラーメッセージに含めたりしない。
• 短命なトークン（OIDC、フェデレーテッドアクセス、時間限定認証）を長期キーより優先。
• シークレットは専用のシークレットマネージャにのみ格納し、ポータルは参照するだけにする。

また監査ログは「誰がいつ何をしたか」を捕らえつつ、シークレット値自体を含めないようにしてください。

現実的な障害の脅威モデルを作る

現実的なリスクに焦点を当てます：

• 過度に広い権限や誤設定されたRBACによる権限昇格
• 検証されていないWebhook/コールバックによる不正なアクション実行
• デバッグエンドポイント、冗長なログ、過度に緩い検索によるデータ漏洩

署名付きWebhook検証、最小権限のロール、読み取りと変更操作の厳格な分離で緩和してください。

CIと権限レビューでチェックを左にシフトする

ポータルコードと生成テンプレートに対してCIでセキュリティチェック（リンティング、ポリシーチェック、依存性スキャン）を実行し、次を定期的にレビューします：

• RBACロールとグループマッピング
• テンプレート権限（誰が何を作れるか）
• “ブレイクグラス”管理アクセスとそのローテーション手順

ガバナンスは一度きりのプロジェクトでなく、定期的で自動化され可視化されることが持続可能です。

ロールアウト、採用、長期運用

ポータルはチームが実際に使ってこそ価値を生みます。ロールアウトをプロダクトローンチとして扱ってください：小さく始め、速く学び、証拠に基づいて拡張します。

集中したパイロットから始める

モチベーションがあり代表的な1～3チームでパイロットを行ってください（“グリーンフィールド”チーム、レガシー多めチーム、より厳しいコンプライアンス要件を持つチーム）。実際のタスク（サービス登録、インフラ要求、デプロイのトリガー）を観察し、摩擦は即座に修正します。目的は機能完備ではなく、ポータルが時間を節約しミスを減らすことを示すことです。

移行を退屈で予測可能にする

移行手順を通常のスプリントに収まるようにしてください。例：

1. 既存サービスをサービスカタログに登録,
2. 所有権とオンコール情報を紐付け,
3. CI/CDを接続,
4. 次の新しいコンポーネントで一つのテンプレートを採用。

“Day 2”のアップグレードは段階的に行えるようにし、チームが徐々にメタデータを追加し、カスタムスクリプトをポータルワークフローに置き換えられるようにします。

読まれるドキュメントとインプロダクトヘルプ

「サービスを登録する」「データベースを要求する」「デプロイをロールバックする」のような主要ワークフローについて簡潔なドキュメントを書いてください。フォームフィールド横にインプロダクトヘルプを置き、詳細は /docs/portal や /support へリンクします。ドキュメントはコードのように扱い、バージョン管理、レビュー、刈り込みを行ってください。

所有は長期的なコミットメント

最初から継続的な所有を計画してください：誰かがバックログをトリアージし、外部ツールへのコネクタを維持し、自動化が失敗したときにユーザーをサポートする必要があります。ポータル障害のSLAを定義し、コネクタ更新の定期的サイクルを設定し、監査ログを定期的にレビューして繰り返す痛点やポリシーギャップを見つけてください。

ポータルが成熟するにつれて、ポータル設定のスナップショット/ロールバック、確実なデプロイ、リージョン間の環境プロモーションのような機能が欲しくなるでしょう。素早く構築・実験する場合、Koder.aiは計画モード、デプロイ/ホスティング、コードエクスポートを備えた内部アプリを立ち上げる手助けになり、ポータル機能を長期的なプラットフォーム要素に固める前のパイロットに有用です。