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 → worktree or tmp）
• 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 の重要フィールド:

ログファイルの直接読み取り

run store のログファイルを直接読むことも可能:

# デフォルトの run store パス
_build/actrun/runs/<run-id>/tasks/<task_id>.stdout.log
_build/actrun/runs/<run-id>/tasks/<task_id>.stderr.log

参考

• https://github.com/mizchi/actrun