Introduce actrun into the project so that GitHub Actions workflows can be run locally.
How to use this skill
Apply this skill when the user requests any of the following:
- Want to introduce actrun into the project
- Want to configure actrun.toml
- Want to make existing workflows actrun-compatible
Installation procedure
Step 1: Installation
# curl (Linux / macOS)
curl -fsSL https://raw.githubusercontent.com/mizchi/actrun/main/install.sh | sh
Docker (no installation required)
docker run --rm -v "$PWD":/workspace -w /workspace ghcr.io/mizchi/actrun workflow run .github/workflows/ci.yml
moon installmoon install mizchi/actrun/cmd/actrun
Build from sourcegit clone https://github.com/mizchi/actrun.git && cd actrun moon build src/cmd/actrun --target native
### Step 2: 環境チェック
```bash
actrun doctor
Check the following:
git: Requiredbash: Requirednode: Required for running Node.js actionsdocker: Required for Docker actions/container jobsnix: When using Nix integration
Step 3: Configuration file generation
actrun init
actrun.toml is generated. It automatically detects tools installed locally and suggests skip settings for the corresponding setup actions.
Step 4: Workflow operation check
# まず dry-run で実行プランを確認
actrun .github/workflows/ci.yml --dry-run
# 問題なければ実行
actrun .github/workflows/ci.yml
actrun.toml configuration guide
Basic configuration
# ワークスペースモード
workspace_mode = "local" # local, worktree, tmp, docker
# ローカルで不要なアクションをスキップ
local_skip_actions = [
"actions/checkout", # ローカルではチェックアウト不要
"actions/setup-node", # ローカルの node を使う
]
# サードパーティアクションを自動信頼
trust_actions = true
Recommended configuration by project type
Node.js project
local_skip_actions = [
"actions/checkout",
"actions/setup-node",
]
Python project
local_skip_actions = [
"actions/checkout",
"actions/setup-python",
]
Go project
local_skip_actions = [
"actions/checkout",
"actions/setup-go",
]
Rust project
local_skip_actions = [
"actions/checkout",
"actions-rust-lang/setup-rust-toolchain",
]
Multiple languages / Nix environment
local_skip_actions = [
"actions/checkout",
"actions/setup-node",
"actions/setup-python",
]
# Nix で全ツールチェーンを提供
# nix_mode = "" # 自動検出(flake.nix / shell.nix)
# nix_packages = ["python312", "nodejs"]
Differential execution configuration
Useful for monorepos and large-scale projects:
[affected."ci.yml"]
patterns = ["src/**", "package.json", "pnpm-lock.yaml"]
[affected."lint.yml"]
patterns = ["src/**", "*.config.*"]
[affected."docs.yml"]
patterns = ["docs/**", "*.md"]
actrun ci.yml --affected # 変更があるときだけ実行
Workflow pattern configuration
# actrun list で表示するワークフローの glob
includes = [".github/workflows/*.yml", "ci/**/*.yaml"]
Making workflows actrun-compatible
ACTRUN_LOCAL conditional branching
When you want to separate behavior between local and GitHub Actions:
steps:
# GitHub Actions でのみ実行(ローカルではスキップ)
- uses: actions/checkout@v5
if: ${{ !env.ACTRUN_LOCAL }}
# ローカルでのみ実行
- run: echo "local debug"
if: ${{ env.ACTRUN_LOCAL }}
Handling secrets
# 環境変数で渡す
ACTRUN_SECRET_GITHUB_TOKEN=$(gh auth token) actrun ci.yml
# .env ファイルを使う
echo "ACTRUN_SECRET_NPM_TOKEN=xxx" >> .env.local
actrun ci.yml --env .env.local
.env.local は .gitignore .
Configuring cron schedules
In the workflow schedule trigger:
actrun cron show # スケジュール確認
actrun cron install # crontab に登録
actrun cron uninstall # crontab から削除
Typical installation flow
# 1. インストール
curl -fsSL https://raw.githubusercontent.com/mizchi/actrun/main/install.sh | sh
# 2. 環境チェック
actrun doctor
# 3. 設定生成
actrun init
# 4. dry-run で確認
actrun .github/workflows/ci.yml --dry-run
# 5. 実行
actrun .github/workflows/ci.yml
# 6. 結果確認
actrun run view run-1
actrun run logs run-1
# 7. (オプション) cron 登録
actrun cron install
Adding to .gitignore
# actrun
actrun.toml # プロジェクトに合わせて共有するか個人用か選択
.env.local # シークレット
_build/actrun/ # run store(デフォルトパス)