clasp run-function セットアップ手順 (Apps Script API executable deploy)

clasp 3.x の clasp run-function <funcName> は CI / ローカル端末から GAS 関数を直接呼び出せる強力な機能ですが、Apps Script API executable deploy 設定と OAuth scope の拡張が必要です。本書は MAS-114 E2E テスト (testMAS114_InvoiceValidation) を CI から自動実行するための一連の手順を整理します。

なぜ必要か

現状の制約:

• MAS-114 のような Spreadsheet 操作を含むテスト関数は Apps Script IDE で関数選択 → 実行ボタン押下で動かしている (GAS UI 経由・人間操作前提)
• clasp run-function を試すと Script function not found. Please make sure script is deployed as API executable. で失敗 (2026-06-24 検証済)
• 起案者の手作業を減らすため、CI から clasp run-function を呼べる自動化が望ましい

期待効果:

• pnpm run push:dev && clasp run-function testMAS114_InvoiceValidation を 1 コマンドで実行
• GitHub Actions の post-merge job で自動 E2E テスト (本 PR シリーズの最終形)
• adversarial review + 静的解析の補完として実機検証を CI に組み込む

前提条件

1. GCP プロジェクトの紐付け — Apps Script Project が GCP project に紐付いていること
   • GAS IDE 左下 ⚙️ → 「Google Cloud Platform (GCP) プロジェクト」で project number 設定
   • dev / prod それぞれ別 GCP project (bizlp-gas-accounting-dev / bizlp-gas-accounting-prod)
2. Apps Script API 有効化 — 上記 GCP project で script.googleapis.com を有効化
   • gcloud services enable script.googleapis.com --project=bizlp-gas-accounting-dev
3. OAuth クライアント ID — Apps Script API が要求する OAuth scope に対応した credential
   • 通常は clasp の default credentials (~/.clasprc.json) を流用するが、scope 拡張が必要

セットアップ手順

Step 1: Apps Script IDE で実行可能 API として deploy

1. dev Spreadsheet (1K6iT...) → 拡張機能 → Apps Script を開く
2. デプロイ → 新しいデプロイ → 種類「実行可能 API」を選択
3. アクセス可能ユーザー: 「自分のみ」
4. デプロイ → デプロイ ID をメモ
5. prod も同様の手順で別途 deploy

Step 2: .clasprc.json の OAuth scope 拡張

~/.clasprc.json の oauth.scope 配列に以下を追加 (clasp 3.x で初回 clasp login 時にも指定可):

"scope": [
  "https://www.googleapis.com/auth/script.projects",
  "https://www.googleapis.com/auth/script.scriptapp",
  "https://www.googleapis.com/auth/script.deployments",
  "https://www.googleapis.com/auth/script.external_request",
  "https://www.googleapis.com/auth/script.scriptapp.execute"
]

詳細スコープ要件: https://developers.google.com/apps-script/api/concepts/authorization

スコープ変更後は clasp login --force で再認証 (既存トークン破棄)。

Step 3: 関数の private 解除確認

末尾 _ の関数は private 扱いで API executable から呼べない (memory [gas-private-underscore-ide-dropdown])。clasp run-function 対象は 末尾 _ なしにする。

// ✅ 呼べる
function testMAS114_InvoiceValidation() { ... }

// ❌ 呼べない (private)
function testMAS114_InvoiceValidation_() { ... }

Step 4: 動作確認

bash scripts/clasp-switch.sh dev
clasp run-function testMAS114_InvoiceValidation

期待出力 (関数が return しない場合は空):

{}

90_test_results シートに結果が書き出されていれば成功。

CI 統合 (GitHub Actions)

.github/workflows/mas-e2e-test.yml (TODO・未実装):

name: MAS E2E Test
on:
  push:
    branches: [main]
    paths:
      - 'mas/400_domain/**'
      - 'mas/900_test/**'
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Restore .clasprc.json from secret
        env:
          CLASPRC_JSON: ${{ secrets.CLASPRC_JSON }}
        run: echo "$CLASPRC_JSON" > ~/.clasprc.json
      - name: Setup clasp
        run: npm install -g @google/clasp@3
      - name: Push to dev
        run: bash scripts/clasp-switch.sh dev && clasp push --force
      - name: Run MAS-114 E2E
        run: clasp run-function testMAS114_InvoiceValidation
      # 結果は 90_test_results シートに書き出される
      # CI job では結果取得のため別途 sheet API call が必要 (or テスト関数が return value で結果を返す形に改修)

CLASPRC_JSON は GitHub Secrets に登録した OAuth token JSON。Apps Script API scope 含む。

トラブルシューティング

関連

• ADR-013: Env モジュール経由の環境値取得(GCP project ID 等)
• memory [gas-private-underscore-ide-dropdown]: 末尾 _ 関数は IDE/API ともに非公開
• memory [scriptid-vs-spreadsheetid]: scriptId と Spreadsheet ID の混同罠
• Google Apps Script API docs: https://developers.google.com/apps-script/api
• clasp 3.x docs: https://github.com/google/clasp

実装ステータス

完了は別 follow-up PR にて。本 PR は手順書のみ。