tomevault-io actrun-debug Skill
actrun のワークフロー実行が失敗した場合に、原因を特定し修正方法を提案する。
このスキルの使い方
ユーザーが以下のいずれかを求めた場合にこのスキルを適用する:
- actrun の実行が失敗して原因を知りたい
- ワークフローのエラーをデバッグしたい
- actrun の出力を解析してほしい
診断手順
Step 1: 実行結果の取得
# 最新の実行一覧を確認
actrun run list
# 失敗した run の詳細を取得
actrun run view <run-id>
# JSON で詳細情報を取得（解析しやすい）
actrun run view <run-id> --json
Step 2: ログの確認
# 全ログを確認
actrun run logs <run-id>
# 失敗したタスクのログを特定して確認
actrun run logs <run-id> --task <job_id>/<step_id>
run view --json の steps 配列から status: "failed" のステップを特定し、その id を --task に渡す。
Step 3: 原因分類と対処
以下のパターンに分類して対処する:
A. ツール未インストール
症状: command not found, No such file or directory
対処:
# 依存ツールチェック
actrun doctor
# ローカルツールがあるならスキップ設定
# actrun.toml:
# local_skip_actions = ["actions/setup-node"]
B. アクション互換性問題
症状: unsupported action input, action not found
対処:
- ビルトイン対応アクションか確認（checkout, cache, artifact, setup-node）
- 未対応アクションは
--skip-actionでスキップ - リモートアクションは
--trustフラグでフェッチ許可
actrun ci.yml --skip-action unsupported/action --trust
C. パス/ワークスペース問題
症状: ファイルが見つからない、パスが違う
対処:
--workspace-modeを変更（local→worktreeortmp）actions/checkoutをスキップしている場合、ファイルがカレントディレクトリにあるか確認
# worktree で隔離実行
actrun ci.yml --worktree
D. シークレット/変数の未設定
症状: ${{ secrets.XXX }} が空、認証エラー
対処:
# シークレットを環境変数で渡す
ACTRUN_SECRET_GITHUB_TOKEN=$(gh auth token) actrun ci.yml
# .env ファイルから読み込み
actrun ci.yml --env .env.local
E. 条件式エラー
症状: if 条件の評価エラー、予期しないスキップ
対処:
--dry-runで実行プランを確認ACTRUN_LOCAL=trueによる条件分岐を確認${{ env.ACTRUN_LOCAL }}が設定されているか確認
F. Nix 関連
症状: nix develop エラー、パッケージが見つからない
対処:
# Nix を無効化して切り分け
actrun ci.yml --no-nix
# アドホックパッケージを指定
actrun ci.yml --nix-packages "nodejs python312"
G. Docker/コンテナ関連
症状: docker: command not found, イメージ pull 失敗
対処:
# Docker が動いているか確認
actrun doctor
# ランタイム変更
actrun ci.yml --container-runtime podman
Step 4: リトライ
# 修正後、失敗ジョブのみリトライ
actrun ci.yml --retry
# 特定ジョブだけ実行
actrun ci.yml --job <failed-job-id>
JSON 出力の解析ポイント
actrun run view <run-id> --json の重要フィールド:
| フィールド | 説明 |
|---|---|
state |
completed, partial_failed, failed |
ok |
全体の成否 (boolean) |
exit_code |
終了コード |
steps[].id |
ステップID (job_id/step_name) |
steps[].status |
success, failed, skipped |
steps[].message |
出力メッセージ |
tasks[].stdout_path |
stdout ログファイルパス |
tasks[].stderr_path |
stderr ログファイルパス |
issues[] |
実行中の警告・問題 |
ログファイルの直接読み取り
run store のログファイルを直接読むことも可能:
# デフォルトの run store パス
_build/actrun/runs/<run-id>/tasks/<task_id>.stdout.log
_build/actrun/runs/<run-id>/tasks/<task_id>.stderr.log
参考
Source: mizchi/actrun — distributed by TomeVault.