Vercel Flags の Project Connections でSDKキーを配らずに別プロジェクトのフラグを評価する
2026年11月2日、Vercel が Vercel Flags の Project Connections を公開しました。同じチーム内であれば、SDK キー（フラグ設定を読み取れるシークレット）をコピーして環境変数に配らなくても、別プロジェクトのフラグを評価できます。接続したコンシューマー側は、自分のデプロイが持つ OIDC トークン（デプロイに自動で付与される ID トークン）で認証します。アクセスの付与・剥奪はダッシュボードか CLI から行え、剥奪に再デプロイは不要です。全プランで利用できます。
一方で、接続はソースプロジェクトの全フラグ・全環境への読み取りを一括で許可する仕組みです。フラグ単位・環境単位での絞り込みはできません。SDK キー方式が不要になったわけではなく、使い分けの判断が必要です。
これまでの方式と何が変わるか
従来、別プロジェクトのフラグを読むには、ソースプロジェクトで環境ごとに SDK キーを作り、コンシューマープロジェクトの環境変数（例: PROJECT_A_FLAGS_KEY）に貼り付ける必要がありました。この方式には運用上の負担が三つあります。キーの保管、ローテーション時の再デプロイ、そして「どのキーをどのプロジェクトに渡したか」の追跡です。SDK キーは環境ごとに発行され、値は作成直後に一度しか表示されません。
Project Connections はこの三つをまとめて消します。認証情報はコンシューマーのデプロイ自身の ID なので、配布も保管もローテーションも発生しません。接続状態はダッシュボードの Connections ページに一覧として残り、「自分のフラグを読んでいるプロジェクト」と「自分が読んでいるプロジェクト」の双方向が可視化されます。
設定手順
前提として、ソースプロジェクト側で Vercel Flags が設定済みであること、そしてチームの Member／Owner ロール、またはソースプロジェクトの Project Admin 権限が必要です。Developer 権限だけでは接続を作成・削除できません。接続の作成時にはコンシューマープロジェクトの閲覧権限も要ります（削除時は不要）。
ダッシュボードでは、ソースプロジェクトの Flags → Connections を開き、「flags can be read by」から新規接続でコンシューマープロジェクトを選びます。コンシューマー側の Connections ページから逆方向に作ることもでき、必要な権限は同じです。
CLI でも管理できます（Vercel CLI 63.0.0 以降）。たとえば storefront に checkout のフラグを読ませるなら vercel flags connections add storefront --project checkout、一覧は vercel flags connections list --project checkout、削除は vercel flags connections remove storefront --project checkout です。CI やセットアップスクリプトに組み込むならこちらが扱いやすい形です。
コード側の書き方とローカル開発
コンシューマーアプリでは @flags-sdk/vercel 1.6.0 以降（コアライブラリを直接使う場合は @vercel/flags-core 1.11.0 以降）を入れ、createVercelAdapter にソースプロジェクトの ID を渡したアダプターを作ります。自分のプロジェクトのフラグ用に vercelAdapter() を併用でき、共有フラグと自前のフラグを同じファイルに並べられます。プロジェクト ID はダッシュボードで接続を展開するとスニペットごとコピーできます。
ローカル開発では、コンシューマーアプリのディレクトリで vercel link と vercel env pull を実行し、.env.local を読み込ませます。ここに含まれる OIDC トークンが接続先フラグへのアクセス権を持ちます。トークンには有効期限があるため、期限切れ時は vercel env pull を再実行します。この「トークンが切れたら引き直す」という挙動は、静的キーを置きっぱなしにできた従来方式との実務上の差分なので、チーム内の開発手順書に明記しておくとつまずきません。
アクセス範囲と環境の対応を先に確認する
接続はソースプロジェクトの全フラグに対する読み取り・評価権限を、全環境まとめて付与します。フラグ単位や環境単位の制限はできません。読み取れる範囲にはターゲティングルールの設定内容も含まれ、ルールにメールアドレスなどの属性が使われていればそれも対象になります。つまり接続の判断は「このフラグを共有してよいか」ではなく「このプロジェクトにフラグ設定全体を見せてよいか」で行う必要があります。
評価される環境はコンシューマー側のデプロイ環境で決まります。Production は Production、Preview は Preview、Development は Development、カスタム環境は Preview にマップされます。ソース側で環境ごとに値を切り替えている場合、コンシューマーの Preview デプロイがソースの Preview 設定を読む点を踏まえて、検証用の値を設計してください。
SDK キーを使い続けるべきケース
Project Connections は「同一チーム内のプロジェクト間」に限られます。次の場合は従来どおり SDK キーが必要です。
- Vercel の外（自社サーバーや他社クラウド）で動くアプリからフラグを読むとき
- 別チームのプロジェクトからフラグを読むとき
- どちらかのプロジェクトを他チームへ移管する予定があるとき
三つめは移行時の落とし穴です。どちらかのプロジェクトを別チームに移管したり削除したりすると接続は解除され、SDK キーへ自動的に切り替わることはありません。移管前に各コンシューマーへ SDK キーを設定して再デプロイしておく、という順序が必要です。
導入時に押さえておきたい運用上の点
まず defaultValue を必ず設定してください。接続を解除すると再デプロイなしでアクセスが切れるため、評価できなくなったときに返る値を各フラグに決めておくことが、そのまま障害時の挙動設計になります。逆に言えば、この「即時剥奪できる」性質は、キー回収と再デプロイが必要だった SDK キー方式より事故対応が速いという利点でもあります。
次にビルドとの関係です。Vercel Flags はビルド時にフラグ定義をデプロイへ埋め込み、実行時にサービスへ到達できない場合のフォールバックに使います。接続先プロジェクトの定義もビルド時に取得されるため、接続を作ってからビルドする順序を守らないと、フォールバック定義に共有フラグが含まれません。既存デプロイに接続を追加した場合は、フォールバックを効かせるために再デプロイしておくのが安全です。
課金の観点では、フラグの評価と設定読み取りはソースプロジェクトの使用量としてカウントされます。これは SDK キー方式と同じ扱いです。多数のマイクロフロントエンドから共有フラグを読む構成では、利用量がソース側に集中する前提でプランを見ておく必要があります。
次に何をするか
すでに SDK キーで横断評価している構成があるなら、まず @flags-sdk/vercel のバージョンを確認し、1.6.0 以降へ更新したうえで、同一チーム内の接続から順に置き換えるのが現実的です。置き換えの単位は「ソースプロジェクト全体を見せてよいコンシューマー」かどうかで切り分け、チームをまたぐ経路や Vercel 外のアプリは SDK キーのまま残します。切り替え後は古い SDK キーを削除し、コンシューマー側の環境変数も消して、認証経路を一本化しておくと運用が追いやすくなります。
