CI

ワークスペースはテキストファイルのフォルダなので、テスト対象のAPIと同じリポジトリに置けます。CIでは、コマンドラインツールがワークスペースをチェックし、リクエストをチェック付きで実行し、 CIシステムが表示するレポートを書き出します。チェックが失敗すると、ジョブも失敗します。

ジョブが行うことCopy Anchor Link

echolot validate Alpenglow.echolot --env staging
echolot run Alpenglow.echolot --env staging \
  --reporter console --reporter junit --out echolot-results.xml

1. echolot validateは、何かを送信する前に、壊れたファイルや欠けている変数を見つけます。
2. echolot runは、リクエストを送信し、チェックとスクリプトを実行します。console はジョブのログに実行内容を出力し、junit はCIがテスト結果として読み取るファイルを書き出します。
3. リクエストが失敗すると終了コードは1になり、ジョブが失敗します。

ワークスペースの一部だけを実行するには --folder、データ駆動の実行には --data、最初の失敗で止めるには --bail、不安定な依存先には --retries を追加します。

CIでのシークレットCopy Anchor Link

ワークスペースのファイルにはシークレットの値が含まれないため、CIが値を渡す必要があります。それぞれをCIのシークレットに保存し、変数名を大文字にした ECHOLOT_SECRET_<NAME> という環境変数として渡します （シークレットを参照）。

または、ファイルに書いて --secrets で渡します。1行に NAME=value を1つ書きます。そのファイルは絶対にコミットしないでください。

ほとんどのCIシステムは CI を設定しており、これによってキーチェーンがオフになるため、ジョブがプロンプトで待たされることはありません。レポートはシークレットの値をマスクするので、 アーティファクトとして保存しても安全です。

• OAuthのMCPサーバ： Macで echolot mcp sign-in <server> --print を使って1回サインインし、出力された ECHOLOT_SECRET_… の値をCIのシークレットとして保存します。 echolot mcpを参照してください。
• キャプチャしたシークレット： キーチェーンがない場合、シークレット変数へのレスポンスのキャプチャは、実行中の次のリクエストに引き継がれません。そのような変数には、CIから値を渡すか、 シークレットではない変数にキャプチャしてください。

GitHub ActionsCopy Anchor Link

macOSランナーで、リリースからツールをダウンロードして実行します。

# .github/workflows/api-checks.yml
name: API checks
on: [push, pull_request]

jobs:
  echolot:
    runs-on: macos-15
    steps:
      - uses: actions/checkout@v4

      - name: Install the Echolot command-line tool
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          gh release download --repo staticdreams/echolot-public --pattern 'echolot-*-macos.zip'
          unzip -o echolot-*-macos.zip -d "$RUNNER_TEMP/echolot"
          echo "$RUNNER_TEMP/echolot" >> "$GITHUB_PATH"

      - name: Check the workspace
        run: echolot validate Alpenglow.echolot --env staging
        env:
          ECHOLOT_SECRET_PASSWORD: ${{ secrets.ALPENGLOW_STAGING_PASSWORD }}

      - name: Run the requests
        run: |
          echolot run Alpenglow.echolot --env staging \
            --reporter console --reporter junit --out echolot-results.xml
        env:
          ECHOLOT_SECRET_PASSWORD: ${{ secrets.ALPENGLOW_STAGING_PASSWORD }}

      - name: Keep the report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: echolot-results
          path: echolot-results.xml

タグを指定しない gh release download は、最新のリリースを取得します。バージョンを固定するには、タグを指定します（gh release download v0.5.0 …）。

LinuxランナーCopy Anchor Link

現時点では、ツールはmacOSで動作します。上のジョブもmacOSランナーを使っています。Linux版、Dockerイメージ、すぐに使えるGitHub Actionはまだ公開されていません。公開されたら、このページで紹介します。

ほかのCICopy Anchor Link

すべてが終了コード付きのコマンドなので、シェルコマンドを実行できるCIシステムならどれでも使えます。macOSランナー向けのスクリプトです。

#!/bin/sh
set -e

echolot validate Alpenglow.echolot --env staging
echolot run Alpenglow.echolot --env staging \
  --reporter console \
  --reporter junit --out reports/echolot.xml \
  --reporter html --out reports/echolot.html

set -e は、最初に失敗したコマンドでスクリプトを止めます。CIのテストレポートの設定で reports/echolot.xml を指定し、reports/echolot.html は、人が開けるようにアーティファクトとして保存してください。

その他のゲートCopy Anchor Link

APIが必要とするがCIにはないサーバには、先にモックをバックグラウンドで実行してください。

空のリポジトリからの手順は、CIでAPIをテストするを参照してください。