CI/CDパイプライン向けプログラム可能なトンネル：一時URLによるWebhookテストの自動化

現代のソフトウェア開発ライフサイクルでは、テストは単に関数が特定の値を返すかどうかを確認するだけではありません。複雑で分散したシステム間の通信が円滑に行われているかを検証することが重要です。高度なQAチームやDevOpsエンジニアにとって、ローカルサーバーを手動で立ち上げたり、コマンドラインのトンネルバイナリを使ってサードパーティの統合をテストしたりするのは過去の話です。今日の高速なチームは自動化を求めており、プログラム的なlocalhostトンネルを利用して、統合テストやCI/CDパイプライン内でエフェメラルURLを直接生成しています。

Stripeのような決済ゲートウェイ、Slackのようなコミュニケーションプラットフォーム、またはGitイベントのための統合を構築している場合、アプリケーションが受信するHTTPリクエストを正しく処理しているかを確認することが最重要です。本記事では、手動のCLIツールからプログラム可能なトンネルへの移行方法、GitHub ActionsでのWebhookテストの実行方法、そしてnpmのlocaltunnelの代替手段の現状について解説します。これらはベンダーの説明ではなく、一次情報に基づいています。

1. 課題：CLIトンネルがCI/CDで失敗する理由

Webhook統合を開発した経験がある場合、標準的なワークフローは次の通りです：

1. ローカルサーバーを起動 (localhost:3000)
2. 新しいターミナルを開き、CLIトンネルコマンドを実行 (ngrok http 3000, lt --port 3000)
3. 生成された公開URLをコピー
4. そのURLをサードパーティのサービスの開発者ダッシュボードに貼り付け
5. イベントをトリガーし、ログを確認

このワークフローはローカル開発には問題ありませんが、自動化されたCI/CD環境では崩れます。パイプラインはヘッドレスで動作しているため、開発者がURLをコピペすることはできません。テストがサードパーティのサンドボックスからライブWebhookを受信する必要がある場合、CIランナーは動的に公開・ルーティング可能なURLをプロビジョニングし、それを外部サービスのAPIに登録し、コールバックを待ち、インフラをクリーンに破棄する必要があります。

CI/CD Webhookのジレンマ

CIジョブは通常、エフェメラルなランナー（隔離されたコンテナやVM）上で実行され、パブリックに到達可能なIPを持ちません。受信Webhookのエンドツーエンドテストを自動化するには、ランナーはオンデマンドで公開URLを提供する必要があります。一般的な回避策はどちらも問題があります：

• Webhookのモック化。 迅速ですが、モックは実際にプロバイダーが送信するペイロード形式を正しく解析していることを証明できず、署名検証やTLSネゴシエーションなどのネットワークレベルのエッジケースをスキップします。
• 静的ステージングサーバーへのポイント。 これにより、隔離された実行の原則に反します。複数のプルリクエストを同時にテストしている場合、PR “A”向けのWebhookがPR “B”のテスト中にステージングサーバーに届く可能性があります。

解決策は、各テスト実行に固有の公開URLをプログラム的に提供し、破棄することです。

2. プログラム可能なlocalhostトンネルとは何か？

プログラム可能なlocalhostトンネルは、アプリケーションコード（Node.js、Python、Go）から直接安全なトンネルをインスタンス化、管理、破棄できる仕組みです。シェルから別のCLIプロセスを呼び出すのではなく、テストセットアップファイル内で、フレームワーク（Jest、Mocha、Playwright）が次の操作を行えます：

1. ローカルテストサーバーを起動
2. トンネルを確立し、awaitして公開URLを取得
3. そのURLを使って外部サービスのAPIに登録
4. 外部イベントをトリガー
5. ローカルサーバーがWebhookを正しく受信・処理したことを検証
6. トンネルとサーバーを終了

これにより、手動の介入が不要となり、テストスイートは任意のCI/CDプラットフォーム上で孤立して並列に確実に動作します。

3. npmのlocaltunnelの代替手段を探す

長年、オープンソースのlocaltunnelパッケージはNode.js開発者のデフォルト選択でした：localtunnel({ port: 3000 })でURLが得られました。しかし、これはもはや安全なデフォルトではありません。2026年中頃現在、localtunnelは2021年以来リリースされておらず、Snykの依存関係分析では非アクティブなメンテナンスと高リスクのaxiosの古いバージョンをバンドルしていることが指摘されています。具体的には、未解決の高リスクの脆弱性（GHSA-wf5p-g6vw-rhxxのCSRFやCVE-2025-27152のSSRF/資格情報漏洩）を含むためです。localtunnel/localtunnel#724のGitHubの未解決Issueも2025年後半時点でnpm auditによりフラグが立っています。これをCIパイプラインで使うのは推奨されません。無料のloca.ltホスティングも負荷時に502エラーやレート制限が多く報告されています。

以下は、プログラム的に使う場合の現実的な代替案の比較です：

A. ネイティブの@ngrok/ngrok Node.js SDK

NgrokはNode.js、Python、Go、Rust向けのネイティブエージェントSDKを提供しています。@ngrok/ngrok npmパッケージはCLIをラップせず、ngrokエージェントをネイティブバインディング経由で直接埋め込みます。

長所： 高い信頼性、TLS組み込み、スクリプト性、成熟したドキュメント、OAuth/IP制限やレートリミット用のトラフィックポリシーエンジン。

短所： 無料プランでも認証トークンが必要（CIで管理する秘密情報が増える）；無料プランは同時オンラインエンドポイント3つとエージェントセッション3つに制限され、多数のPRビルドを並列実行する場合にボトルネックとなる。

無料プランの事実確認： ngrokの公式ドキュメントによると、無料エンドポイントはセッションタイムアウトなしで無期限に稼働可能です。比較記事で流布されている「2時間で切断される」というのは誤りです。無料プランの制限は、使用量と同時実行数（3エンドポイント、3エージェント、月間1GB帯域、20,000リクエスト）です。

B. Cloudflare Tunnel (cloudflared)

ゼロトラストに焦点を当てたチーム向けに、Cloudflare TunnelはCloudflareのエッジネットワークを利用した信頼性の高いエフェメラルURLを提供します。ngrokとは異なり、公式のCloudflare SDKは存在しません。cloudflaredバイナリをサブプロセスとして実行する方法が一般的です。コミュニティパッケージ（npmのcloudflaredやnode-cloudflared）は、そのバイナリを型付きAPIでラップしますが、これは従来のCLIハックに近い方法です。

長所： エンタープライズレベルのセキュリティ、Cloudflareのエッジネットワークを活用、WAFやアクセス制御と連携可能。

短所： ネイティブSDKよりもセットアップが重い；trycloudflare.comを使ったクイックトンネルは稼働保証がなく、あくまで一時的なテスト用途に適しています。

C. LocalXpose

LocalXposeはHTTP、HTTPS、TCP、TLS、UDPといったマルチプロトコルをサポートし、非HTTPWebhookやデータベース接続、ゲームサーバのUDPトラフィックもトンネリング可能です。公式のNode.jsクライアントライブラリ（localxpose）も提供されており、実際にプログラム的にトンネルを作成できます：

const LocalXpose = require('localxpose');
const client = new LocalXpose(process.env.LOCALXPOSE_ACCESS_TOKEN);

const httpTunnel = await client.http({
    to: '127.0.0.1:3000',
    subdomain: 'ci-test',
});

console.log(`トンネルが稼働中：${httpTunnel.addr}`);
// ... アサーションを実行 ...
await httpTunnel.close();

長所： @ngrok/ngrokでは対応できないプロトコル（ネイティブUDP）もサポート、Node SDKの提供、サブドメインや予約ドメインの利用可。

短所： ngrokよりコミュニティとエコシステムが小さく、ゲスト/未認証層はレート制限あり。

D. InstaTunnel

InstaTunnel（instatunnel.my）は、新しく積極的に開発されているトンネリングサービスで、CLIやホストされたダッシュボード、REST APIも公開しています。ngrokの無料枠の制限に対して具体的な比較を行う場合、マーケティング資料の数値（無料セッション長、無料同時トンネル数、コスト比較）はベンダーのブログやMediumの投稿からのものであり、独立したベンチマークではありません。これらの数値は信頼できますが、CIワークフローに組み込む前に最新の料金ページと比較してください。

E. Pinggy.io

Pinggyは従来、SSH経由での利用が一般的でした：ssh -p 443 -R0:localhost:3000 a.pinggy.io。ローカルインストール不要でCIランナーに適していました。現在は、公式のNode.js SDK（@pinggy/pinggy）やPython SDKも提供されており、SSH出力を解析せずにトンネルを管理できます：

import { pinggy } from "@pinggy/pinggy";

const tunnel = await pinggy.createTunnel({ forwarding: "localhost:3000" });
await tunnel.start();
console.log("トンネルURL：", await tunnel.urls());

よくある誤解：SSHコマンドはJSONを返さず、URLは標準出力にプレーンテキストで出力されます。JSON /urlsエンドポイントは存在しますが、これはPinggyのWeb Debugger（追加のローカルポートをフォワードして有効化）から取得します。SDKのtunnel.urls()はより直接的に構造化された結果を得る方法です。Pinggyの無料プランは現在、セッション60分と1つの同時トンネルに制限されています。長時間または高並列の利用には有料トークンが必要です。

CI/CDにおける結論

Node.jsでテストを書き、UDPを必要としない場合、公式の@ngrok/ngrok SDKが最も成熟した選択肢です。ただし、その無料枠の同時接続数制限を考慮してください。もしその制限がボトルネックなら、LocalXposeやPinggyのSDKも有効な代替手段です。Cloudflare Tunnelは、すでにCloudflareのエッジを標準化している場合に最適ですが、バイナリを管理する必要があります。

4. Node.jsでのプログラム可能なトンネルの実装例

以下は、Jestと@ngrok/ngrok SDKを使ったWebhookハンドラーの統合テスト例です。模擬決済プロバイダー向けです。

ステップ1：依存関係のインストール

npm install express
npm install --save-dev jest @ngrok/ngrok axios

（Expressはv4.16以降でexpress.json()が標準搭載されているため、body-parserは不要です。）

ステップ2：統合テストの作成

// __tests__/webhook.integration.test.js
const express = require('express');
const ngrok = require('@ngrok/ngrok');
const crypto = require('crypto');
const axios = require('axios');

let server;
let listener;
let publicUrl;
let receivedWebhook = null;

const app = express();
app.use(express.json());

app.post('/webhook', (req, res) => {
    if (req.body && req.body.event === 'payment.success') {
        receivedWebhook = req.body;
        return res.status(200).send('Webhook Received');
    }
    return res.status(400).send('Invalid Webhook');
});

describe('Webhookのエンドポイント自動テスト', () => {

    beforeAll(async () => {
        // 1. ローカルサーバーを起動（空きポートを自動割当）
        server = app.listen(0);
        const port = server.address().port;

        // 2. プログラム的トンネルを起動
        // NGROK_AUTHTOKENは環境変数に設定済みとする
        listener = await ngrok.forward({
            addr: port,
            authtoken_from_env: true,
        });
        publicUrl = listener.url();
        console.log(`トンネル作成先：${publicUrl}`);
    });

    afterAll(async () => {
        // 3. トンネルとサーバーを終了
        if (listener) await listener.close();
        if (server) server.close();
    });

    it('外部サービスからWebhookを受信・処理できること', async () => {
        // 4. 一時URLを外部サービスに登録（実際はAPI呼び出し）
        const webhookEndpoint = `${publicUrl}/webhook`;

        const externalCall = await axios.post(webhookEndpoint, {
            event: 'payment.success',
            transactionId: crypto.randomUUID(),
        });

        // 5. アサーション
        expect(externalCall.status).toBe(200);
        expect(receivedWebhook).not.toBeNull();
        expect(receivedWebhook.event).toBe('payment.success');
    });
});

この方法のポイント:

• ポートの競合回避。 app.listen(0)はNode.jsに空きポートを割り当てさせ、トンネルはそのポートにバインドします。
• 隔離性。 各実行ごとに新しいURLが生成され、並列実行間での干渉を防ぎます。
• エンドツーエンドの検証。 実際のHTTP通信、TLSハンドシェイク、ペイロードのパースを行います。

5. GitHub ActionsでのWebhookテスト

ローカルでの実行は簡単ですが、ヘッドレスのCI/CD環境では設定やネットワーク制約、トークンの安全な管理が必要です。

シークレットの管理

1. GitHubリポジトリの設定 > Secrets and variables > Actionsに進む
2. NGROK_AUTHTOKENなどのシークレットを作成

ワークフローファイルの設定例

# .github/workflows/webhook-integration-tests.yml
name: Webhook統合テスト

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test-webhooks:
    name: プログラム的トンネルテスト実行
    runs-on: ubuntu-latest

    steps:
      - name: リポジトリのチェックアウト
        uses: actions/checkout@v5

      - name: Node.js環境のセットアップ
        uses: actions/setup-node@v6
        with:
          node-version: '24'
          cache: 'npm'

      - name: 依存関係のインストール
        run: npm ci

      - name: 統合テストの実行
        env:
          NGROK_AUTHTOKEN: ${{ secrets.NGROK_AUTHTOKEN }}
          STRIPE_SECRET_KEY: ${{ secrets.STRIPE_SECRET_KEY }}
        run: |
          echo "プログラム的Webhookテストを開始します..."
          npm run test:integration

Node 24は2026年8月現在のActive LTSです。Node.js 20は2026年4月にEOLを迎え、GitHub Actionsも2026年中にNode.js 20のランナーから移行予定です。actions/checkout@v5とactions/setup-node@v6は最新のメジャーバージョンです。

高度な考慮点

• エフェメラルランナーの制約。 テストがサードパーティのバックグラウンドジョブ完了を待つ場合、タイムアウトとjest.setTimeout()を調整してください。
• ゴーストプロセスのリスク。 テストがクラッシュした場合やafterAllが実行されない場合、ngrokのエージェントセッションが残ることがあります。ngrok/ngrok#148のIssueでは、listener.close()やngrok.disconnect()が必ずしもセッションを終了しないケースが報告されています。
• レートリミット。 複数のPRが同時にワークフローをトリガーすると、無料プランの同時トンネル数制限に達しやすいです。シリアル化、専用の認証情報、または有料プランの検討を。
• サンドボックスモードの利用。 一時的な公開URLは本番環境ではなく、Stripe Test ModeやGitHubのテスト環境に向けて使用してください。

6. 自動エンドポイントテストのベストプラクティス

リトライロジックの実装

ネットワーク遅延や遅延に対応し、結果をポーリングしてください：

// Webhook受信待ちのユーティリティ関数
const waitForWebhook = async (timeoutMs = 5000) => {
    const startTime = Date.now();
    while (Date.now() - startTime < timeoutMs) {
        if (receivedWebhook) return receivedWebhook;
        await new Promise(resolve => setTimeout(resolve, 200)); // 200msごとにポーリング
    }
    throw new Error('Webhookがタイムアウト内に受信されませんでした');
};

セキュリティの検証

トンネルを使ってセキュリティ機構を直接テストします：

• 署名検証。 ペイロードに意図的に改ざんしたHMAC署名を付与し、エンドポイントが401を返すか確認
• リプレイ攻撃。 同じ署名済みペイロードを2回送信し、冪等性が保たれるか確認
• 不正なペイロード。 不完全なJSONを送信し、サーバーが400を返すか確認

モックとライブトンネルの使い分け

すべてのテストでライブトンネルを使う必要はありません。内部ロジックのユニットテストはトンネルなしで行い、エンドツーエンドの統合テストにのみプログラム的トンネルを使います。これにより、テストの速度と信頼性を維持します。

7. まとめ

手動CLIトンネリングから、プログラム的に管理されるインプロセスのトンネルへの移行は、テストスイートの成熟度を高めます。@ngrok/ngrokは最も成熟したネイティブSDKですが、他にもLocalXposeやPinggyのSDK、Cloudflare Tunnelも選択肢です。選択前に、セッション長、同時接続数、料金などのベンダーの実際の制限を確認してください。

---

変更履歴

メタデータ削除： 実際に画像を埋め込んでいない画像キャプションやタイトルブロックのアーティファクトを除去。

修正点：

1. localtunnelの信頼性に関する記述。 2021年以来リリースがなく、依存関係に未解決の高リスク脆弱性を含むことを明示。
2. ngrok無料プランのセッション長。 2時間のタイムアウトは誤情報であり、実際は無期限で稼働可能と記載。
3. ngrokの料金体系。 現在の価格（Hobbyist $10/月、Pay-as-you-go $20/月）を追記。
4. ngrok.disconnect()とlistener.close()の違い。 現行APIに基づき、listener.close()を例示し、ngrok.disconnect(url)も有効と記載。
5. ゴーストプロセスの具体的な事例。 ngrok/ngrok-javascript#148のIssueを引用。
6. Cloudflare Tunnel SDKの誤解を修正。 公式SDKはなく、trycloudflare.comはアップタイム保証なしと明記。
7. LocalXposeのSDK対応を確認。 公式Node.jsライブラリとコード例を追加。
8. InstaTunnelの記述を修正。 数値の出典を明示し、自己報告の比較内容を削除。
9. Pinggyの情報を大幅に更新。 SSHだけでなくSDKも提供、無料のセッション制限も明記。
10. GitHub Actionsのバージョン更新。 actions/checkout@v4 → @v5、actions/setup-node@v4 → @v6、Node.jsバージョンも更新。
11. 不要なbody-parserの削除。 Express v4.16以降はexpress.json()で十分。
12. supertestの削除。 使われていなかったため。

追加情報：

• LocalXposeの公式Node.js SDKのコード例
• Pinggyの公式Node.js SDKのコード例
• ngrokの具体的な無料プランの数値
• GitHubのIssue番号（ngrok/ngrok-javascript#148）を記載