act を使用したローカルアクション検証

Jules (またはその他のエージェント) が act を使用して GitHub Actions ワークフローをローカルで実行し、プッシュ前にコード変更が CI に合格することを確認できるようにリポジトリをセットアップします。

セットアップ内容

ローカル CI 検証を可能にする 2 つのスクリプトと agents.md セクション:

1. install-act.sh — act がない場合はインストール (プラットフォーム対応、sudo フォールバック)
2. run-act.sh — act をバックグラウンド実行し、エージェントのタイムアウトを回避するためログポーリングを実施
3. AGENTS.md セクション — Jules がこれらのスクリプトの使用方法を知るための手順

セットアップ手順

ステップ 1: スクリプトをリポジトリにコピー

このスキルの scripts/ ディレクトリを対象リポジトリの scripts/act/ にコピー:

対象ディレクトリ構造:
scripts/act/
├── install-act.sh
└── run-act.sh

スクリプトに実行権限があることを確認:

chmod +x scripts/act/install-act.sh scripts/act/run-act.sh

ステップ 2: AGENTS.md に手順を追加

以下のセクションをリポジトリの AGENTS.md ファイルに追記 (ファイルがない場合は作成)。これは Jules がローカル検証機能を発見する方法です:

## Local CI Verification

Before pushing code or opening a PR, verify changes pass CI locally using `act`.

### Prerequisites
- Docker must be running
- If `act` is not installed, run: `bash scripts/act/install-act.sh`

### How to Verify

1. Read `.github/workflows/` to find the CI workflow and identify the job ID
2. Run the verification script:
   ```bash
   bash scripts/act/run-act.sh "push -j <JOB_ID>"

With matrix: bash scripts/act/run-act.sh "push -j <JOB_ID> --matrix <KEY>:<VALUE>" 3. If the run fails, read the log output, fix the code, and re-run 4. After verification, clean up:

rm -f act_output.log
git checkout <any unintended file changes>

Configuration

• Timeout: ACT_TIMEOUT=900 bash scripts/act/run-act.sh "..." (default: 600s)
• Poll interval: ACT_POLL=15 bash scripts/act/run-act.sh "..." (default: 10s)
• Custom image: pass -P ubuntu-latest=node:20-bookworm in the arguments for faster pulls

### ステップ 3: .gitignore を更新

`.gitignore` に以下のエントリを追記 (存在しない場合):

act artifacts

act_output.log .secrets

### ステップ 4: ユーザーに次のステップを印刷

ユーザーに以下を伝えます:
1. 検証を実行するマシン (または Jules VM) には Docker がインストールされ、実行されている必要があります
2. `act` は初回使用時に `scripts/act/install-act.sh` 経由で自動インストール
3. ワークフローがシークレットを必要とする場合、`.secrets` ファイルを作成 (KEY=VALUE 形式) — コミットしないこと
4. 生成されたすべてのファイルをコミット

## トラブルシューティング

- **Docker が実行されていない**: `act` は Docker が必要です。Docker デーモンが起動していることを確認
- **イメージプルが遅い**: 初回実行で 2GB+ ダウンロード。高速プルのため `-P ubuntu-latest=node:20-bookworm` を使用
- **ARM64 の問題**: Apple Silicon では act 引数に `--container-architecture linux/amd64` を追加
- **シークレット必須**: `.secrets` ファイルを作成し、act 引数に `--secret-file .secrets` を渡す
- **タイムアウト**: `ACT_TIMEOUT=1200 bash scripts/act/run-act.sh "..."` で増加

## リソースリファレンス

- [Troubleshooting Guide](resources/troubleshooting.md) — 一般的な問題の詳細な解決策