#actrun

#Install

# npx (no install required)
npx @mizchi/actrun workflow run .github/workflows/ci.yml

# curl (Linux / macOS)
curl -fsSL https://raw.githubusercontent.com/mizchi/actrun/main/install.sh | sh

# Docker
docker run --rm -v "$PWD":/workspace -w /workspace ghcr.io/mizchi/actrun workflow run .github/workflows/ci.yml

# npm global install
npm install -g @mizchi/actrun

# Nix (run without installing)
nix run github:mizchi/actrun -- workflow run .github/workflows/ci.yml

# Nix (install into profile)
nix profile install github:mizchi/actrun

# moon install
moon install mizchi/actrun/cmd/actrun

# Build from source
git clone https://github.com/mizchi/actrun.git && cd actrun
moon build src/cmd/actrun --target native

#Nix

#Run directly

nix run github:mizchi/actrun -- workflow run .github/workflows/ci.yml

#Build from source

nix build github:mizchi/actrun
./result/bin/actrun workflow run .github/workflows/ci.yml

#Development shell

echo "use flake" > .envrc
direnv allow

nix develop

#Adding the overlay to your flake.nix

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
    actrun.url = "github:mizchi/actrun";
  };

  outputs = { nixpkgs, actrun, ... }:
    let
      system = "aarch64-darwin"; # or "x86_64-linux"
      pkgs = import nixpkgs {
        inherit system;
        overlays = [ actrun.overlays.default ];
      };
    in
    {
      packages.${system}.default = pkgs.actrun;
      devShells.${system}.default = pkgs.mkShell {
        packages = [ pkgs.actrun ];
      };
    };
}

#Without flakes

# default.nix provides a ready-to-use derivation
let
  actrun = import (builtins.fetchTarball "https://github.com/mizchi/actrun/archive/main.tar.gz") { };
in
  actrun

#Quick Start

# Run a workflow locally
actrun workflow run .github/workflows/ci.yml

# Show execution plan without running
actrun workflow run .github/workflows/ci.yml --dry-run

# Emit flow cache plan JSON for an external orchestrator
actrun workflow run .github/workflows/ci.yml \
  --dry-run \
  --json \
  --flow-cache-store /tmp/flow-cache.json \
  --flow-signature build=sig-build

# Skip actions not needed locally (e.g. setup tools already installed)
actrun workflow run .github/workflows/ci.yml \
  --skip-action actions/checkout \
  --skip-action extractions/setup-just

# Run in isolated worktree
actrun workflow run .github/workflows/ci.yml \
  --workspace-mode worktree

# Generate config file
actrun init

# View results
actrun run view run-1
actrun run logs run-1 --task build/test

#Configuration

# Workspace mode: local, worktree, tmp, docker
workspace_mode = "local"

# Skip actions not needed locally
local_skip_actions = ["actions/checkout"]

# Trust all third-party actions without prompt
trust_actions = true

# Nix integration: "auto" (force), "off" (disable), or empty (auto-detect)
nix_mode = ""

# Additional nix packages
nix_packages = ["python312", "jq"]

# Container runtime: docker, podman, container, lima, nerdctl
container_runtime = "docker"

# Include uncommitted changes in worktree/tmp workspace
# include_dirty = true

# Default local GitHub context when `--event` is omitted
# [local_context]
# repository = "owner/repo"
# ref_name = "main"
# before_rev = "HEAD^"
# after_rev = "HEAD"
# actor = "your-name"

# Override actions with local commands
# [override."actions/setup-node"]
# run = "echo 'using local node' && node --version"

# Affected file patterns per workflow
# [affected."ci.yml"]
# patterns = ["src/**", "package.json"]

#Flow Cache

#CLI Reference

#Workflow Commands

actrun workflow list                 # List workflows in .github/workflows/
actrun workflow run <workflow.yml>    # Run a workflow locally

#Run Commands

actrun run list                      # List past runs
actrun run view <run-id>             # View run summary
actrun run view <run-id> --json      # View run as JSON
actrun run watch <run-id>            # Watch until completion
actrun run logs <run-id>             # View all logs
actrun run logs <run-id> --task <id> # View specific task log
actrun run download <run-id>         # Download all artifacts

#Analysis Commands

# Lint: type check expressions and detect dead code
actrun lint                          # Lint all .github/workflows/*.yml
actrun lint .github/workflows/ci.yml # Lint a specific file
actrun lint --ignore W001            # Suppress a rule (repeatable)

# Visualize: render workflow job dependency graph
actrun viz .github/workflows/ci.yml              # ASCII art (terminal)
actrun viz .github/workflows/ci.yml --mermaid    # Mermaid text (for Markdown)
actrun viz .github/workflows/ci.yml --detail     # Mermaid with step subgraphs
actrun viz .github/workflows/ci.yml --svg        # SVG image
actrun viz .github/workflows/ci.yml --svg --theme github-light

#Lint Diagnostics

[lint]
preset = "default"  # default, strict, oss
ignore_rules = ["unknown-property", "unused-outputs"]

#Visualization Example

$ actrun viz .github/workflows/release.yml

┌───────┐    ┌────────┐
│ build │    │ docker │
└───────┘    └────────┘
    └┐
     │
┌─────────┐
│ release │
└─────────┘

#Artifact & Cache Commands

actrun artifact list <run-id>                          # List artifacts
actrun artifact download <run-id> --name <name>        # Download artifact
actrun cache list                                      # List cache entries
actrun cache prune --key <key>                         # Delete cache entry

#Workflow Run Flags

#Affected Runs

1. actrun.toml [affected."<workflow>"] patterns
2. on:push:paths from the workflow file (automatic fallback)

# Compare against last successful run (default)
actrun ci.yml --affected

# Compare against a specific rev
actrun ci.yml --affected HEAD~3
actrun ci.yml --affected abc1234

# Preview what would happen (shows plan even if skipped)
actrun ci.yml --affected HEAD~1 --dry-run

[affected."ci.yml"]
patterns = ["src/**", "package.json"]

[affected.".github/workflows/lint.yml"]
patterns = ["src/**", "*.config.*"]

on:
  push:
    paths: ["src/**", "*.toml"]  # actrun --affected uses these

#Workspace Modes

#Container Runtime

# CLI flag
actrun workflow run ci.yml --container-runtime podman

# actrun.toml
container_runtime = "podman"

# Environment variable (also works)
ACTRUN_CONTAINER_RUNTIME=podman actrun workflow run ci.yml

#Supported GitHub Actions

#Builtin Actions (deterministic emulation)

#Remote Actions (fetch + execute)

• GitHub repo node actions with pre/main/post lifecycle
• GitHub repo docker actions with pre-entrypoint/entrypoint/post-entrypoint lifecycle
• Composite actions (local and remote)
• docker://image direct execution

#Self-Hosted WASM Optimization

• A self-hosted runner may prefer a sibling *.wasm file next to a standard node* action runs.main
• The same action still runs on GitHub Actions through the normal JS fallback path
• The runtime family is selected with --wasm-runner / ACTRUN_WASM_RUNNER

#Local-Only Execution Flag

steps:
  # Skipped when running locally (runs on GitHub Actions)
  - uses: actions/checkout@v5
    if: ${{ !env.ACTRUN_LOCAL }}

  # Runs only locally (skipped on GitHub Actions)
  - run: echo "local debug info"
    if: ${{ env.ACTRUN_LOCAL }}

#Action Overrides

[override."actions/setup-node"]
run = "echo 'using local node' && node --version"

local_skip_actions = ["actions/checkout"]

[override."actions/setup-node"]
run = "echo 'using local node'"

[override."actions/setup-python"]
run = "python3 --version"

#Secrets & Variables

# Provide secrets via environment variables
ACTRUN_SECRET_MY_TOKEN=xxx actrun workflow run ci.yml

# Provide variables
ACTRUN_VAR_MY_VAR=value actrun workflow run ci.yml

#Environment Variables

#Nix Integration

#Auto-detection

#Examples

# Auto-detect flake.nix / shell.nix
actrun workflow run .github/workflows/ci.yml

# Disable nix wrapping
actrun workflow run .github/workflows/ci.yml --no-nix

# Ad-hoc packages without flake.nix
actrun workflow run .github/workflows/ci.yml --nix-packages "python312 jq"

# Disable via environment variable
ACTRUN_NIX=false actrun workflow run .github/workflows/ci.yml

#Typical flake.nix for Rust

{
  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.11";
  outputs = { self, nixpkgs }:
    let
      systems = [ "x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin" ];
      forAllSystems = nixpkgs.lib.genAttrs systems;
    in {
      devShells = forAllSystems (system:
        let pkgs = nixpkgs.legacyPackages.${system};
        in { default = pkgs.mkShell { packages = [ pkgs.rustc pkgs.cargo ]; }; });
    };
}

#Typical flake.nix for Python + uv

{
  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.11";
  outputs = { self, nixpkgs }:
    let
      systems = [ "x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin" ];
      forAllSystems = nixpkgs.lib.genAttrs systems;
    in {
      devShells = forAllSystems (system:
        let pkgs = nixpkgs.legacyPackages.${system};
        in { default = pkgs.mkShell { packages = [ pkgs.python312 pkgs.uv ]; }; });
    };
}

#Notes

• Only run: steps are wrapped. uses: action steps are not affected.
• Job container: steps skip nix wrapping (container has its own environment).
• nix develop / nix-shell is invoked per step, so the nix environment is consistent across steps.

#Workflow Features

• Push trigger filter (branches, paths)
• strategy.matrix (axes, include, exclude, fail-fast, max-parallel)
• Job/step if conditions (success(), always(), failure(), cancelled())
• needs dependencies with output/result propagation
• Reusable workflows (workflow_call) with inputs, outputs, secrets, secrets: inherit, nested expansion
• Job container and services with Docker networking
• Expression functions: contains, startsWith, endsWith, fromJSON, toJSON, hashFiles
• File commands: GITHUB_ENV, GITHUB_PATH, GITHUB_OUTPUT, GITHUB_STEP_SUMMARY
• Shell support: bash, sh, pwsh, custom templates ({0})
• step.continue-on-error, steps.*.outcome / steps.*.conclusion

#Performance

• local — lowest overhead, best for fast iteration
• nix-packages — +0.6s startup for nix develop; execution speed identical to local
• apple-container — +0.9s startup; many-file I/O is 3-4x faster (ext4 vs APFS metadata)

# Try it yourself
nix run github:mizchi/actrun -- workflow run .github/workflows/ci.yml

#Development

just              # check + test
just fmt          # format code
just check        # type check
just test         # run tests
just e2e          # run E2E scenarios
just release-check  # fmt + info + check + test + e2e

#Live Compatibility Testing

# One-shot: dispatch, wait, download, compare
just gha-compat-live compat-checkout-artifact.yml

# Step by step
just gha-compat-dispatch compat-checkout-artifact.yml
just gha-compat-download <run-id>
just gha-compat-compare compat-checkout-artifact.yml _build/gha-compat/<run-id>

#Architecture

#Prior Art

• actionlint — Static checker for GitHub Actions workflow files. actrun lint is inspired by its rule design and type system.

#License

#actrun

• push trigger のフィルタ判定
• workflow YAML subset parser
• workflow/job/step 契約型
• ActionRef / resolver
• bitflow IR への lowering
• bitflow task cache plan / writeback の CLI 連携 (--flow-cache-store, --flow-signature)
• workflow list の最小 read-only CLI
• workflow run の最小 subcommand
• strategy.matrix の最小対応 (axes / include / exclude / mixed axes + include / fail-fast / max-parallel)
• matrix job に対する needs fan-in と aggregated ${{ needs.<job>.result }} / ${{ needs.<job>.outputs.* }}
• minimal job-level if: (success() default, always() / failure() / cancelled(), simple github.* / needs.* comparison)
• minimal step-level if: (success() default, always() / failure() / cancelled())
• minimal expression functions (contains, startsWith, endsWith, fromJSON, toJSON, hashFiles)
• ${{ vars.* }} の最小対応 (ACTRUN_VAR_<NAME> から供給)
• ${{ secrets.* }} の最小対応 (ACTRUN_SECRET_<NAME> から供給, if: 直接参照は未対応)
• workflow_call trigger と inputs / outputs / secrets の parse / contract 対応
• local / remote reusable workflow (jobs.<job_id>.uses) の最小実行 (with, workflow_call.inputs の required / implicit default / type validation, caller job の strategy.matrix, matrix caller 上の workflow_call.outputs 集約, workflow_call.outputs, secrets mapping, secrets: inherit, nested reusable workflow, remote reusable workflow 内 local action)
• job container の string / mapping form の parse / contract 対応と、run step / GitHub repo node* action を docker adapter で実行する最小対応
• job container 配下の GitHub repo / direct runs.using: docker action を sibling container として実行し、job container の volume mount を共有する最小対応
• job container 配下で actions/checkout@* が host 側に materialize した workspace を後続 container run step から見える形で扱う最小対応
• job container 配下で actions/upload-artifact@* / actions/download-artifact@* の roundtrip を後続 container run step から扱う最小対応
• job services の mapping form の parse / contract 対応、service container の最小 lifecycle 実行、${{ job.services.<id>.ports[...] }} context、health check wait、job container との docker network 共有の最小対応
• workflow/job permissions / concurrency の parse / contract 対応と lowering reject
• step-level continue-on-error
• ${{ steps.<id>.outcome }} / ${{ steps.<id>.conclusion }} の最小対応
• native host executor
• CLI run store の最小対応 (--run-root, _build/actrun/runs/<run-id>/run.json, jobs.json, artifacts.json, caches.json, tasks/*.stdout.log|stderr.log|summary.md, jobs/artifacts/caches index, timestamps, run list, run view, run watch, run logs, run download, artifact list, artifact download, cache list, cache prune)
• local injection point の CLI flag 対応 (--artifact-root, --cache-root, --github-action-cache-root, --registry-root)
• bit repo から push commit を materialize する runtime
• uses: actions/checkout@* と uses: builtin://checkout の最小 builtin 対応
• actions/checkout の path / sparse-checkout / sparse-checkout-cone-mode / fetch-depth / ref / clean / submodules の最小 builtin 対応
• uses: actions/upload-artifact@* / uses: actions/download-artifact@* の最小 builtin 対応 (directory, wildcard path, if-no-files-found, overwrite, download-all directory mode, merge-multiple)
• uses: actions/setup-node@* の最小 builtin 対応 (node-version, cache: npm, registry-url)
• job container 配下で actions/setup-node@* が PATH shim と output を後続 run step に伝播する最小対応
• uses: actions/cache@* / actions/cache/restore@* の restore-keys, lookup-only, fail-on-cache-miss 対応
• job container 配下で actions/cache@* の miss -> deferred save -> next job restore を後続 container run step から扱う最小対応
• native prefetch による owner/repo[/path]@ref GitHub repo action の remote fetch / cache fill
• cache 済み owner/repo[/path]@ref GitHub repo composite action の workspace-aware 展開
• cache 済み / prefetched owner/repo[/path]@ref GitHub repo node* action の最小実行
• cache 済み / prefetched owner/repo[/path]@ref GitHub repo runs.using: docker action の最小実行
• uses: ./path の local composite action 展開
• local composite action 内の nested uses 展開
• local composite action の with と ${{ inputs.* }} の最小対応
• CI, GITHUB_ACTIONS, GITHUB_WORKSPACE, GITHUB_WORKFLOW, GITHUB_JOB の基本 env 注入
• GITHUB_ACTION の最小対応
• cached / prefetched GitHub action 向けの GITHUB_ACTION_REPOSITORY, GITHUB_ACTION_REF 注入
• local composite action inner step への GITHUB_ACTION_PATH 注入
• local composite action inner step 間に閉じた GITHUB_STATE の最小対応
• cache 済み / prefetched GitHub repo node* action の pre / main / post lifecycle と GITHUB_STATE 共有
• cache 済み / prefetched GitHub repo runs.using: docker action の pre-entrypoint / entrypoint / post-entrypoint lifecycle と GITHUB_STATE 共有
• GITHUB_ENV, GITHUB_PATH, GITHUB_OUTPUT, GITHUB_STEP_SUMMARY の file command 対応
• native run step における ${{ env.* }} の最小対応
• direct dependency に対する ${{ needs.<job>.outputs.<name> }}, ${{ needs.<job>.result }} の最小対応
• push workflow における ${{ github.ref }}, ${{ github.ref_name }}, ${{ github.sha }} と GITHUB_REF, GITHUB_REF_NAME, GITHUB_SHA の最小対応
• push workflow における ${{ github.event_name }} と GITHUB_EVENT_NAME の最小対応
• push workflow における ${{ github.repository }} と GITHUB_REPOSITORY の最小対応
• push workflow における ${{ github.repository_owner }} と GITHUB_REPOSITORY_OWNER の最小対応
• push workflow における ${{ github.actor }} と GITHUB_ACTOR の最小対応
• native run step における ${{ github.workflow }}, ${{ github.job }}, ${{ github.workspace }} の最小対応
• native run step における ${{ github.action }} の最小対応
• cached / prefetched GitHub action 文脈での ${{ github.action_repository }}, ${{ github.action_ref }} の最小対応
• local composite action inner step における ${{ github.action_path }} の最小対応
• native run step における ${{ runner.os }}, ${{ runner.arch }}, ${{ runner.temp }}, ${{ runner.environment }} の最小対応
• file-based な bash / sh / pwsh 実行と {0} 付き custom shell template の最小対応
• job 内の後続 step に対する ${{ steps.<id>.outputs.<name> }} の最小対応
• uses: docker://... の native docker 実行
• MVP 範囲外機能の明示的 reject

#例

///|
test {
  let workflow = new_workflow(
    "ci",
    [
      new_job("build", [
        new_run_step("install", "pnpm install"),
        new_run_step("test", "pnpm test"),
      ]),
      new_job("lint", [new_run_step("lint", "pnpm lint")], needs=["build"]),
    ],
    trigger=new_push_trigger(branches=["main"], paths=["src/*"]),
    defaults=new_run_defaults(shell=Some("bash")),
  )

  let event = new_push_event("main", ["src/lib.mbt"])
  inspect(matches_push_trigger(workflow.trigger, event), content="true")

  let src =
    #|on: push
    #|jobs:
    #|  build:
    #|    runs-on: ubuntu-latest
    #|    steps:
    #|      - run: pnpm test
  let parsed = parse_workflow_yaml(src)
  let lowered = lower_push_workflow(parsed.workflow.unwrap())
  @debug.debug_inspect(lowered.errors, content="[]")
  @debug.debug_inspect(lowered.ir.tasks.length(), content="2")
}

#MVP 非対応

• pwsh binary が存在しない環境での PowerShell workflow 実行
• reusable workflow の広い互換対応
• custom registry action の remote fetch / registry protocol 解決