wrkflw — Validate and Run GitHub Actions Workflows Locally

Introduction

wrkflw is a command-line tool that validates GitHub Actions workflow files and runs them locally in Docker containers. Instead of pushing commits just to see if your CI passes, you can iterate on workflows at your desk and catch errors before they reach GitHub.

What wrkflw Does

• Parses and validates .github/workflows/*.yml files against the Actions schema
• Runs workflow jobs locally in Docker or Podman containers
• Supports matrix strategy expansion to test multiple configurations
• Provides an interactive TUI for selecting which jobs and steps to run
• Filters workflows by changed files (diff-aware mode)

Architecture Overview

wrkflw is written in Rust for fast startup and low resource usage. The validator parses YAML workflow files and checks them against the GitHub Actions specification, reporting syntax errors, unknown actions, and missing inputs. The runner creates Docker containers that mimic the GitHub-hosted runner environment, mounts the repository, and executes each step sequentially. Matrix builds spawn parallel containers.

Self-Hosting & Configuration

• Install via Cargo: cargo install wrkflw
• Alternatively, download pre-built binaries from GitHub Releases
• Requires Docker or Podman for running workflows locally
• Configure runner images in .wrkflw.toml (default: ubuntu-latest equivalent)
• Set secrets and environment variables via the config file or CLI flags

Key Features

• Fast YAML validation catches errors without running anything
• Docker-based execution mirrors the GitHub Actions environment
• Interactive TUI for browsing and selectively running jobs
• Diff-aware filtering to run only workflows affected by recent changes
• Matrix strategy support for testing combinatorial build configurations

Comparison with Similar Tools

• act — the original local Actions runner in Go; wrkflw adds a TUI and diff-aware filtering
• GitHub CLI (gh workflow run) — triggers remote runs; wrkflw runs everything locally
• nektos/act — mature Go implementation; wrkflw is newer with a Rust core and interactive UI
• actionlint — lints workflow YAML; wrkflw validates and runs workflows
• CI locally with Docker Compose — manual setup; wrkflw automates the container orchestration

FAQ

Q: How close is the local environment to GitHub-hosted runners? A: wrkflw uses community-maintained runner images that replicate the ubuntu-latest toolchain. Some GitHub-specific features (OIDC, caching service) are not available locally.

Q: Can I use custom Docker images? A: Yes. Set the container image per job in your workflow or override it in .wrkflw.toml.

Q: Does wrkflw support composite actions and reusable workflows? A: Basic composite action support is available. Reusable workflow (workflow_call) support is under development.

Q: Is Podman supported in addition to Docker? A: Yes. wrkflw detects Podman automatically if Docker is not installed.

Sources

• https://github.com/bahdotsh/wrkflw
• https://crates.io/crates/wrkflw