Skip to main content
自己ホスト環境は Team および Enterprise プランでパブリックベータ版です。利用可能性と制限事項に有効化パスが記載されています。このページは CI テストレシピです。セットアップについてはクイックスタートを、フリートレシピについては本番環境へのデプロイをご覧ください。
自己ホスト環境では、Claude Code のクラウドセッションは、ユーザーが構築・管理する実行イメージ上で実行されます。新しいイメージを本番環境にロールアウトする前に、スクリプトからテスト環境に対して完全なセッションを実行します。セッションを作成し、Claude の返信を読み取り、フォローアップを送信し、その返信も読み取ります。これは実行イメージ、git アクセス、カスタムツールを検証する CI スモークテストの形です。 このレシピは、環境と実行イメージのセットアップが完了していることを前提としています。また、CI ジョブがテストスクリプトと同じホスト上で実行イメージプロセスを開始することを想定しています。これは新しい実行イメージをテストするための自然なセットアップです。実行イメージにインストールする Stop フックは、各ターンの最終返信をローカルファイルに書き込み、スクリプトがそこから読み取ります。そのため、Anthropic API への呼び出しは 2 つのディスパッチだけです。テスト実行イメージが別のインフラストラクチャ上にある場合は、リモートテスト実行イメージをご覧ください。

テスト実行イメージにキャプチャフックをインストールする

読み取りは Claude Code のStop フックを通じて機能します。Claude がターンを完了すると、フックは最終アシスタントメッセージを stdin JSON の last_assistant_message として受け取り、$E2E_REPLY_DIR/<session_id>.txt に追加します。commit-nudge Stop フックと同じ方法でインストールします。実行イメージホストの ~/.claude/ にインストールします。実行イメージはこれをすべてのセッションにシードします。

フックファイルを保存する

実行イメージホストに以下の 2 つのファイルを保存します。
  • 設定ブロック:実行イメージホストの ~/.claude/settings.json にマージします
  • スクリプト:実行イメージホストに ~/.claude/hooks/e2e-stop-hook-capture.sh として保存し、実行可能にします

実行イメージを開始する前に

フックには以下の要件があります。
  • 実行イメージを開始する前にインストールします。実行イメージは起動時に ~/.claude/ をスナップショットするため、実行中の実行イメージに追加されたフックは再起動後にのみ有効になります。
  • 実行イメージプロセスに E2E_REPLY_DIR をエクスポートします。フックは変数が未設定または ディレクトリが存在しない場合は no-op です。実行イメージを開始する場所(systemd ユニット、pod spec、CI ステップなど)で設定します。以下のテストスクリプトもこれが必要です。
このフックはテスト環境にサービスを提供する実行イメージにのみインストールします。E2E_REPLY_DIR が存在するたびにすべてのセッションの最終返信をディスクに書き込みます。これは使い捨ての CI 実行イメージでは無害ですが、変数が誤って設定される可能性がある本番環境実行イメージには含めるべきではありません。

テストループを実行する

--environment および --ref のディスパッチフラグを使用するには、スクリプトを実行するマシンに Claude Code v2.1.224 以降が必要です。これはランナー自体と同じ最低バージョンです。フックを設定し、このホストでランナーを起動した状態で、テストスクリプトは次の処理を行います。
  1. claude -p "<prompt>" --environment <environment-id> --output-format json を使用して、テスト環境上にセッションを作成します。CLI が origin リモートからリポジトリを自動検出できるように、このコマンドは Git のチェックアウト内から実行してください。オプションの --ref <branch> を指定すると、セッションのチェックアウトをローカルの HEAD ではなく指定した ref に基づいて作成します。このコマンドは Claude の応答を待たずに終了します。出力される内容によって、スクリプトは結果を判断できます。
    • セッションが作成された場合: {"ok":true,"session_id":"session_...","title":"...","url":"...","pool_id":"..."} のような 1 行の JSON
    • セッションの作成に失敗した場合: {"ok":false,"error":"..."} という行が出力され、コマンドはステータス 1 で終了します
    • それ以前の段階で発生する一部のエラー(組織でクラウドセッションが利用できない場合や、プロンプトが指定されていない場合など): JSON 行は出力されず、エラーが stderr に出力され、コマンドはステータス 1 で終了します
  2. ターンの完了時にランナー上の Stop フックによって書き込まれる $E2E_REPLY_DIR/<session_id>.txt に応答が現れるのを待ちます。
  3. claude -p "<message>" --cloud <session_id> --output-format json を使用してフォローアップを送信します(実行中のセッションにフォローアップメッセージを送信するを参照)。このコマンドは既存のセッションにユーザーイベントを投稿して終了します。
  4. 手順 2 と同じ方法で、フォローアップへの応答を待ちます。

--environment のディスパッチ動作

Claude Code はセッションを作成し、セッション ID とセッションへのリンクを出力して終了します。 このフラグは remote.defaultEnvironmentId 設定よりも優先されます。--output-format stream-json には対応しておらず、--resume、--continue、--teleport、--session-id、--init-only など、セッションの再開、アタッチ、または事前設定を行うフラグと組み合わせることはできません。--cloud は、セッション ID または URL を指定した場合、および非対話型の実行で説明を伴う場合には拒否されます。値を伴わない --cloud は指定されていないものとして扱われます。ターミナルからは、位置引数のプロンプトの代わりに、タスクを --cloud の説明として渡すことができます。

スクリプト例

このスクリプト例は、テストランナーと同じマシンで実行します。実行する前に、そのマシンを準備します。
  • リポジトリのチェックアウト: セッションで作業させたいリポジトリの git チェックアウトからスクリプトを実行します。
  • ランナー: キャプチャフックをインストールし、E2E_REPLY_DIR をエクスポートした状態で、このホストでランナーを開始します。
  • サインイン: CI からの認証で説明しているとおり、スクリプトを実行するマシンで claude.ai アカウントにサインインします。
  • 環境 ID: CLAUDE_TEST_ENVIRONMENT_ID にテスト環境の ccpool_... ID を設定します。この ID は管理ページの環境詳細ダイアログに表示されるか、環境作成呼び出しによって返されます。
以下のスクリプトは $CLAUDE_TEST_ENVIRONMENT_ID に対して完全なループを実行し、各返信のセンチネルフレーズをアサートします。
TURN1/TURN2 プロンプトと EXPECT1/EXPECT2 センチネルを、カスタム MCP ツールの 1 つを実行するよう Claude に依頼し、その出力をアサートするなど、セットアップを実行するものに置き換えます。

リモートテスト実行イメージ

テスト実行イメージが別のインフラストラクチャ上にある場合(CI ジョブがファイルシステムを共有できない永続的な Kubernetes フリートなど)、Stop フックのファイル書き込みをドライバーがリッスンするエンドポイントへの POST に置き換えます。
ドライバー側では、POST を受け入れ、テストが要求するまで返信を保持するものを実行します。CI ジョブ内の小さな HTTP リスナーや、既に実行している webhook レシーバーなどです。フックはインフラストラクチャ上で実行されるため、エンドポイントは実行イメージからのみ到達可能である必要があります。

CI から認証する

claude -p ... --environment と claude -p ... --cloud の両方は claude.ai OAuth トークンで認証します。sk-ant-xxxxx などの API キーはどちらの呼び出しでも受け入れられません。2 つのアプローチにより、CI でトークンを利用できるようになります。

長期間存続する CI ホスト

スクリプトを実行するマシン上で、自動化用の専用ユーザーアカウントを使用して、claude auth login を 1 回対話的に実行します。Claude Code はトークンを macOS では OS キーチェーンに、Linux と Windows では ~/.claude/.credentials.json に保存します。キーチェーンに書き込みできない macOS ホスト(SSH セッションでログインキーチェーンがロックされたままの場合など)では、Claude Code はトークンを ~/.claude/.credentials.json にも保存します。認証情報管理を参照してください。 CLI は各呼び出しで短期アクセストークンを自動的に更新しますが、基盤となるリフレッシュトークングラントは初期ログインから 30 日間に制限されているため、そのホストで 30 日ごとに claude auth login を対話的に再実行してください。

エフェメラル CI 実行イメージ

現在、これに対する長期間存続する CI トークンはありません。クラウドセッション制御を付与するスコープ user:sessions:claude_code はサーバー側で 30 日間に制限されているため、1 年間の推論のみのトークンを発行する claude setup-token はこれをカバーしていません。環境シークレットも受け入れられません。これは実行イメージが環境に登録することのみを認可し、セッションを作成することは認可しないためです。 エフェメラル実行イメージに保存されたログインをプロビジョニングするには、CLAUDE_CODE_OAUTH_REFRESH_TOKEN と CLAUDE_CODE_OAUTH_SCOPES を設定して、claude auth login がブラウザなしでトークンを交換できるようにします。リフレッシュグラントに対して同じ 30 日間の上限が適用されます。人間のアカウントにバインドされていないマシンアイデンティティパスが必要な場合は、Anthropic アカウントチームにお問い合わせください。

専用テスト環境を作成する

CI の各実行ごとにクリーンな環境を取得するために、環境をプログラムで作成および削除します。CI ジョブが開始する runner がこのフレッシュな環境に登録されます。以下の作成および削除呼び出しは、claude.ai の Cloud environments 管理ページが使用するのと同じエンドポイントであり、anthropic-beta: ccr-byoc-2025-07-29 ヘッダーが必要です。

管理トークンを生成する

$ADMIN_TOKEN は、Owner ロールを保持するアカウントの claude.ai OAuth アクセストークンであり、CI から認証すると同じ方法で生成されます。
  • 生成する: Owner ロールを保持するアカウントで claude auth login を実行してから、長期間実行される CI ホストが Claude Code がそれを保存した場所を示す場所から現在のアクセストークンを読み取ります。
  • 各実行ごとにフレッシュに読み取る: CLI はアクセストークンをローテーションし、同じ 30 日間のリフレッシュ許可上限が適用されるため、コピーを保存しないでください。
  • stdin 経由で渡す: 例が行うように、トークンが curl の引数リストまたはビルドログに記録されないようにします。

環境を作成する

レスポンスをキャプチャして出力しないようにします。pool_secret は、runner を環境に登録できる長期間有効な認証情報であるため、マスクされた CI シークレットとして保存し、環境 ID のみを出力します。トークンをプロセスリストから除外する -H @- 形式には curl 7.55 以降が必要です。古い curl は @- をリテラルヘッダーとして扱い、認可なしでリクエストを送信します。
Owner が組織に対して Allow self-hosted environments をオンにするまでは、呼び出しは 403 permission_error で失敗し、self-hosted runners are disabled by your organization's policy と表示されます。 このホストで runner を開始します。SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET=$ENVIRONMENT_SECRET と、キャプチャフックをテスト runner にインストールするに従う capture hook および E2E_REPLY_DIR を使用してから、テストスクリプトを実行します。

環境を削除する

各 CI 実行がクリーンな状態で開始されるように、実行が終了したときに環境を削除します。