この機能が登場した背景

チームで Vercel プロジェクトを複数運用していると、フィーチャーフラグを 1 つ共有するためだけにサーバー SDK キーをコピーし、環境変数に貼り付けた経験があるのではないでしょうか。この方法は手軽な反面、次のような問題を抱えています。

  • キーをコピーした時点で、どのプロジェクトがどのキーを持っているかの追跡が難しくなります。
  • キーをローテーションすると、消費側プロジェクトをすべて再デプロイする必要があります。
  • ローカル開発では .env にキーを別途記載する必要があり、誤コミットによる情報漏洩のリスクが付きまといます。

今回公開された Project Connections はこの課題に正面から取り組みます。ポイントは「キーを共有しない」ことです。消費側プロジェクトは自身のデプロイの OIDC アイデンティティで認証し、ソースプロジェクトはそのアクセスを読み取り専用で許可します。根拠資料は Vercel 公式チェンジログ を参照してください。

要点: SDK キーのコピーから、OIDC ベースのプロジェクト間認証へ移行する仕組みです。

Developer dashboard showing Vercel Flags connections between projects with read-only access System Abstract Visual

実際の導入手順

1) 接続の作成

接続は次の 2 通りで作成できます。

  • ダッシュボード: プロジェクト → Flags セクション → Connections ページ
  • CLI: vercel flags connections (Vercel CLI 63.0.0 以上が必要)

接続はすべての環境に対して読み取り専用で付与されます。どの環境のフラグを評価するかは消費側のデプロイが決定します。たとえば本番デプロイは自動的に本番フラグを評価します。

2) 消費側コードにアダプターを設定

ソースプロジェクトの ID を渡すだけで、キーは不要です。

// flags/next アダプターでソースプロジェクトに接続する例
import { flag } from 'flags/next';
import { createVercelAdapter } from '@flags-sdk/vercel';

// ソースプロジェクト ID のみ指定します。SDK キーは不要です。
const sharedFlagsAdapter = createVercelAdapter({
  projectId: 'prj_source',
});

// 接続先プロジェクトで定義されたフラグをそのまま評価します。
export const newCheckout = flag({
  key: 'new-checkout',
  defaultValue: false,
  adapter: sharedFlagsAdapter(),
});

3) ローカル開発環境

ローカルでは vercel env pull を実行するとプロジェクトの OIDC トークンが取得されます。.env に SDK キーを手動で記載する必要はありません。チームメンバーのオンボーディング時に「キーはどこで受け取るの?」という質問がなくなるということです。

4) アクセスの失効 (Revoke)

接続を解除しても再デプロイは不要です。これは想像以上に大きな違いです。従来はキーを変更すると消費側プロジェクトの再ビルドが必要でしたが、接続解除はダッシュボードからワンクリックで完了します。

5) バージョン要件

  • @flags-sdk/vercel 1.6.0 以上
  • コアライブラリを直接利用する場合は @vercel/flags-core 1.11.0 以上
  • CLI で接続を管理する場合は Vercel CLI 63.0.0 以上

すべてのプランで利用可能である点も押さえておきましょう。

Code editor displaying Vercel adapter setup for cross-project feature flag evaluation

メリット・デメリットと実務上の注意点

項目従来方式 (SDK キー共有)Project Connections
認証方式サーバー SDK キー (長期シークレット)デプロイの OIDC アイデンティティ (短期)
キーローテーション消費側の再デプロイが必要再デプロイ不要 (接続解除のみ)
ローカル開発.env でキーを手動管理vercel env pull で自動取得
権限範囲キー権限そのまま (広い)読み取り専用に限定
監査・追跡キー配布状況の把握が困難プロジェクト単位で接続管理
プラン制約なしすべてのプランで利用可能

注意すべきポイント

  • 読み取り専用である点を忘れないでください。消費側からソースプロジェクトのフラグを変更することはできません。フラグ値を変更する場合はソースプロジェクト側で行います。
  • 環境マッピングは消費側のデプロイ基準です。消費側がプレビューデプロイであれば、ソースプロジェクトのプレビューフラグを評価します。「プレビューで本番フラグが見えるのはなぜ?」という混乱が生じやすいポイントです。
  • バージョン要件は CI パイプラインで強制しておきましょう。@flags-sdk/vercel 1.6.0 未満ではサイレントに失敗する可能性があります。
  • 接続解除は即時反映されます。消費側でフォールバック値がどう振る舞うかを事前に確認しておくと安全です。

Vercel CLI terminal executing flags connections command for multi-project flag management IT Technology Image

まとめと次のステップ

Project Connections は「フィーチャーフラグをチーム単位の資産として扱う」という方向性を示しています。キーをコピーして貼り付ける方式は速い反面、プロジェクトが増えるほど管理負債が膨らみます。OIDC ベースの認証に移行すれば、セキュリティ面も縮小し、キーローテーションの地獄からも解放されます。

実務適用のヒント

  1. モノレポではなくマルチプロジェクト構成のチームにとって最も効果を実感しやすい機能です。特にマーケティングサイトとアプリが分離している構成で有用です。
  2. フラグの所有権を明確にしてください。ソースプロジェクトが「フラグ定義の単一情報源 (Single Source of Truth)」となります。
  3. CI でバージョンチェックを自動化し、@flags-sdk/vercel の最低バージョンを強制しましょう。

あわせて読みたい記事

次のステップとしては、Vercel Flags の A/B テスト連携やフラグのライフサイクル管理に関するドキュメントを併せて読むことをおすすめします。フラグは結局のところ「削除すること」が最も難しい作業ですから。

本コンテンツは、信頼性の高い情報源をもとにAIツールを活用して作成され、編集者によるレビューを経て公開されています。専門家によるアドバイスの代替となるものではありません。