mcpField
G
gb-setup

gb-setup

github.com/growthbook開発25102 回インストール4 週間前に更新
リポジトリ

gb-setup について

gb-setupは、GrowthBook Agent SkillsをGrowthBook Cloudまたはセルフホスト環境に接続するためのセットアップスキルです。認証情報とアプリのオリジンを検証し、制限付き権限で設定を保存します。

主な機能

  1. 01既存設定の検出とシークレットのマスキング
  2. 02APIキーとHTTPSオリジンの検証
  3. 03認証情報とアプリオリジンの確認
  4. 04権限を制限した設定ファイルの書き込み
  5. 05環境変数によるファイル値の上書き

活用シーン

  1. 01GrowthBook Agent Skillsの初回設定
  2. 02セルフホストGrowthBookのAPIとUIのオリジン設定
  3. 03認証情報を検証してから設定を保存

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/growthbook/skills --skill gb-setup

インストール後、Claude Code で/gb-setupを入力して読み込まれたか確認します。

詳細

gb-setup

GrowthBook Agent Skills のセットアップを、1 つのスキルで行います。GB_API_KEY に加え、セルフホストの場合は GB_API_URL と GB_APP_URL の設定をユーザーに案内します。認証情報と信頼できるアプリのオリジンを検証し、chmod 600 を指定して ~/.config/growthbook/.env に書き込みます。

API キーは GrowthBook ユーザーに紐づく Personal Access Token（PAT）です。そのため、書き込みスキルが作成するフラグや実験はすべて、API によって自動的にそのユーザーの作成物として記録されます。別途、所有者識別子を設定する必要はありません。

対応する環境変数が設定されていない場合、gb-call はこのファイルを読み込みます。そのため、ユーザーはシェルの rc ファイルを編集する必要がなく、一度だけ設定すれば済みます。環境変数がファイルより常に優先されるため、CI や一時的な上書きに便利です。

使用する前に、現在のクライアントに応じて同梱ヘルパーのパスを解決してください。Claude Code プラグインでは ${CLAUDE_PLUGIN_ROOT}/scripts/gb-call、スタンドアロンの Agent Skills インストールでは、このスキルディレクトリを基準とした scripts/gb-call です。以下では、解決したコマンドを <gb-call> に置き換えてください。

ワークフロー

  1. 現在の状態を確認します。 すでに設定されている内容を確認します。ユーザーが値を変更したい場合を除き、すでに設定されている値を尋ねないでください。

    test -f ~/.config/growthbook/.env && echo "exists" || echo "missing"

    ファイルが存在する場合は、Read ツールで読み込み、KEY=value の各行を解析して、マスクした概要を提示します。

    I see existing config at ~/.config/growthbook/.env:
  GB_API_KEY = gb_pat_****wxyz   (last 4 shown)
  GB_API_URL = (not set — defaults to https://api.growthbook.io)
  GB_APP_URL = (not set — defaults to https://app.growthbook.io because the API URL uses GrowthBook Cloud)

Want to keep these, update one, or start fresh?

    GB_APP_URL が未設定の場合は、有効な API オリジンに基づいて説明します。API オリジンが GrowthBook Cloud の場合は https://app.growthbook.io がデフォルトになりますが、カスタムのセルフホスト GB_API_URL が設定されている場合は必須です。

    process.env の設定内容も知らせます。ユーザーがシェルで環境変数をエクスポートしている場合、それらはファイルの値より優先されます。そのことを伝えてください（「シェル環境で GB_API_KEY も設定されています。シェル変数の設定を解除しない限り、ファイルの値は使用されません。」）。

  2. GB_API_KEY を収集します（必須）。既存の値をそのまま使う場合はスキップします。それ以外の場合は、ユーザーが情報に基づいて選択できるよう、まず会話内容への露出に関する注意を伝えてください。

    キーを貼り付ける前にご確認ください。このチャットに入力した内容はエージェントクライアントに保存され、会話の一部として設定済みのモデルプロバイダーに送信される場合があります。このスキルは返信内でキーをマスクしますが、貼り付けた値を後からマスクすることはできません。気になる場合は、クライアントの保存と保持に関する設定を確認してください。

    おすすめ：個人用の管理者トークンを使い回すのではなく、このプラグイン専用の新しい PAT を生成してください。そうすれば、問題が発生した場合でも、他の API アクセスに影響を与えずに個別に取り消せます。

    次に、以下のように尋ねてください。

    Personal Access Token（PAT）または Secret Key を貼り付けてください。以下から取得できます。

    PAT は gb_pat_、Secret Key は secret_ で始まります。どちらも使用できます。

    取得後は、以降のどの手順でも値をそのまま表示しないでください。末尾 4 文字以外をすべてマスクしてください。

  3. セルフホストかどうかを尋ねます（GB_API_URL と GB_APP_URL は任意です）。

    GrowthBook Cloud（api.growthbook.io）とセルフホストのどちらを使用していますか？

    • Cloud → スキップし、両方の URL を未設定のままにします（gb-call は API 呼び出しに https://api.growthbook.io、UI リンクに https://app.growthbook.io をデフォルトで使用します）。
    • セルフホスト → 以下を個別に尋ねます。
      • GB_API_URL に保存する API オリジン（例：https://api.acme-internal.com）。
      • GB_APP_URL に保存する、ユーザー向け GrowthBook UI のオリジン（例：https://growthbook.acme-internal.com）。

    一方のオリジンから他方を推測しないでください。セルフホストのデプロイでは、互いに無関係なホスト名が使われる場合も、API と UI が同じオリジンで提供される場合もあります。

    受け入れる前に、各 URL の形式を検証してください。

    • URL として解析できる必要があります（つまり、new URL(value) が例外をスローしないこと）。
    • スキームは https:// である必要があります（http:// は拒否してください。平文通信での認証ヘッダーは認証情報が漏えいするためです。また、file://、data:// なども拒否してください）。
    • ホスト名は空であってはなりません。
    • ユーザー名やパスワードを含めてはなりません。
    • パス、クエリ、ハッシュを含めてはなりません — new URL(value).pathname は / または空で、search と hash は空である必要があります。https://api.acme.com/v1 のような値は、リクエストやリンクの送信先を気付かれないまま誤らせる可能性があります。オリジンのみを指定するよう求めるメッセージを表示して拒否してください。
    • 保存する前に、末尾のスラッシュを1つ取り除きます。

    これらのチェックに失敗した URL は拒否し、再入力を求めてください。黙って修正してはいけません。黙った修正は、値がシステムでは直せない形で間違っていることがあるにもかかわらず、システムが「何でもうまくやってくれる」とユーザーに思わせてしまいます。

  4. 実際の API で検証します。 収集した値を一時的な環境変数として設定し、軽量な認証済みエンドポイントを呼び出します。

    GB_API_KEY='<value>' \
GB_API_URL='<cloud default or self-hosted API origin>' \
GB_APP_URL='<cloud default or self-hosted app origin>' \
  <gb-call> GET /api/v1/projects

    結果を次のように解釈します。

    • 2xx → 認証情報は機能しています。次に進みます。
    • 401 / 403 → 「認証に失敗しました。API キーが無効、期限切れ、または取り消されています。<url-from-step-2> で新しいキーを生成して、もう一度お試しください。」ステップ2に戻ります。
    • growthbook.io ホストでの 404 → 「api.growthbook.io から 404 が返されました。セルフホスト環境をお使いの場合は、GB_API_URL を API のベース URL に設定してください。」ステップ3に戻ります。
    • ネットワークエラー／DNS エラー → 「<host> に接続できませんでした。URL とネットワークを確認してください。」生のエラーを表示します。

    検証が完了するまで先に進まないでください。ユーザーが行き詰まった場合は、停止してデバッグできるようにしてください。壊れた設定を書き込んではいけません。

    次に、信頼できるアプリのオリジンが期待どおりに解決されることを確認します。

    GB_API_URL='<cloud default or self-hosted API origin>' \
GB_APP_URL='<cloud default or self-hosted app origin>' \
  <gb-call> app-origin

    出力は末尾のスラッシュなしで、期待される UI オリジンと完全に一致する必要があります。一致しない場合はステップ3に戻ります。

  5. ~/.config/growthbook/.env に書き込みます — セキュリティのため、順序が重要です。

    ディレクトリを作成し、まずアクセスを制限します。

    mkdir -p ~/.config/growthbook
chmod 700 ~/.config/growthbook

    ディレクトリの 0700（所有者のみ）権限によって、次の手順の実行中に他のシステムユーザーがファイルを読み取れないよう保護されます。先にファイルを書き込んでから chmod を実行すると、ファイルはユーザーの umask（通常は 0022 → モード 0644、全ユーザーから読み取り可能）を引き継ぐため、その間に読み取り可能な状態が生じます。ディレクトリのアクセスを制限すれば、その状態を防げます。0700 のディレクトリ内のファイルは、ファイルのモードにかかわらず、他のユーザーからアクセスできません。

    次に、クライアントのファイル書き込みツールでファイルを書き込みます。形式は、1行に KEY=value を1つです。引用符は付けません（値にスペース、=、改行が含まれることはありません）。

    GB_API_KEY=<value>
GB_API_URL=<value or omit line>
GB_APP_URL=<value or omit line>

    その後、念のためファイルのモードを設定します。

    chmod 600 ~/.config/growthbook/.env

    0600 は、所有者のみが読み書きできることを意味します。ディレクトリを 0700、ファイルを 0600 にすれば、他のシステムユーザーはこのシークレットにアクセスできません。

  6. 報告します。 ユーザーに次の内容を伝えてください。

    • ファイルの場所（~/.config/growthbook/.env）。
    • ファイルの内容（API キーはマスクし、末尾4文字のみ表示）。
    • gb-call app-origin が返す、信頼できる UI オリジン。
    • 環境変数はファイルより優先されること（CI や一時的な上書きは引き続き機能します）。
    • gb-setup スキルを再実行するとファイルが更新されること。
    • 次に役立つと思われるもの：フラグを確認するための feature-flags スキル（flag-search ワークフロー）、または過去の結果を確認するための experiments スキル（experiment-brainstorm ワークフロー）。

ガードレール

  • API キーを平文で絶対にそのまま返さないでください。 必ず末尾の 4 文字以外をマスクしてください。スキルの出力は、ユーザーのターミナルとトランスクリプトに残ります。
  • ユーザーがキーを貼り付ける前に、トランスクリプトに露出するリスクを伝えてください。 チャットに入力された値はエージェントクライアントに保存される場合があり、設定済みのモデルプロバイダーに送信されます。スキルから後でその値を削除することはできません。管理者トークンの再利用ではなく、新たにスコープを限定した PAT を使うよう、必ず推奨してください。これは過剰な警戒ではありません。ユーザーが会話型インターフェースにシークレットを貼り付ける必要があるワークフローでは、適切な対応です。
  • 失効に関する案内は、脚注ではなく実際の解決策です。 キーが一度でも露出した場合、効果的な対処方法は <GB_APP_URL>/account/personal-access-tokens（またはクラウド環境のデフォルト）で失効させ、ローテーションすることだけです。ユーザーが古いキーや共有キーについて懸念を示した場合は、必ずこの方法を案内してください。
  • ファイルを書き込む前にディレクトリを 0700 にし、書き込み後にファイルを 0600 にしてください。 順序が重要です。Write ツールはユーザーの umask を引き継ぐため、ほとんどのシステムではファイルがモード 0644（全ユーザーから読み取り可能）で作成されます。先にディレクトリのアクセスを制限しておけば、Write と chmod の間の短い時間も、他のユーザーからアクセスできません。その後、多層防御としてファイルにも chmod を適用します。どちらも必須です。片方でも省略すると PAT が漏えいします。
  • 各環境変数は、ファイルよりも環境変数の値が優先されます。 process.env に値が設定されている場合、gb-call はその変数のファイル内の値を無視します。両方が設定されている場合は、実際にどちらの値が有効なのかユーザーが理解できるよう、必ず伝えてください。
  • 形式だけでなく、実際のエンドポイントで検証してください。 「正しそうに見える」だけで動作しないトークンは、トークンがないよりも悪い状態です。ユーザーは設定が完了したと思ってしまいます。GET /api/v1/projects は軽量で、認証が必要であり、すべてのプランで利用できます。
  • オーナー識別子は収集しません。 PAT は GrowthBook ユーザーに紐づいているため、書き込みを行うスキル（flag-create、experiment-launch）では、API がトークンのユーザーに新しいフラグと実験を自動的に関連付けます。セットアップ時にメールアドレスや userId を尋ねないでください。
  • 行の値の先頭にある空白は削除せず、末尾の空白は削除してください。 PAT に空白は含まれないはずです。クリップボードから末尾の改行が付いた状態で貼り付けられた場合は、それを削除してください。先頭の空白は珍しいため、黙って修正するよりユーザーに知らせる方が安全です。
  • 不完全なファイルを書き込まないでください。 検証に失敗した場合は、~/.config/growthbook/.env に手を加えずに停止してください。ユーザーがセットアップをやり直します。動作する設定を、壊れた設定で上書きしてはいけません。
  • 両方の URL から末尾のスラッシュを削除してください。 gb-call は GB_APP_URL も正規化しますが、保存するオリジンを整えておけば、出力の不整合やスラッシュの重複による不具合を避けられます。
  • GB_API_URL から GB_APP_URL を推測しないでください。 api. を app. に置き換える慣例は、セルフホスト環境では保証されません。アプリのオリジンは明示的に尋ねてください。
  • 実際には使用しない環境変数を提案しないでください。 使用するのは GB_API_KEY、GB_API_URL、GB_APP_URL だけです。それ以外はスコープの逸脱となり、今後のコントリビューターを混乱させます。

ファイル形式のリファレンス

~/.config/growthbook/.env：

GB_API_KEY=gb_pat_abc123def456
GB_API_URL=https://api.your-self-hosted.com
GB_APP_URL=https://growthbook.your-self-hosted.com

# で始まる行はコメントです。空行は無視されます。引用符は使わず、値は最初の = から行末までをそのまま読み取ります。

使用するエンドポイント

  • GET /api/v1/projects — 検証専用です。軽量で、認証が必要であり、すべてのプランで利用できます。

引き継ぎ先

  • feature-flags スキル（flag-search ワークフロー）— セットアップ完了後の最初の呼び出し先として最適です（必須入力はなく、新しい設定を確認できます）。
  • experiments スキル（experiment-brainstorm ワークフロー）— 組織に停止済みの実験がすでにある場合は、すぐに表示します。
  • 設定に関するエラーを出すスキルは、すべてここを参照してください。

コメント

Markdown 対応