The provided content is a description of the wrkflw project, which is a command-line tool for validating and executing GitHub Actions workflows locally. Here's the markdown version of the content:
# Validate and Run GitHub Actions Workflows Locally with WRKFLW
Allows you to validate and execute GitHub Actions workflows on your local machine.
**Key Features**
- A terminal user interface (TUI) for managing and monitoring workflow executions
- Validate workflow files with proper exit codes for CI/CD integration
- Execute workflows using Docker or Podman containers
- Support for multiple container runtimes: Docker, Podman, and emulation
- Automatic job dependency resolution
- Container integration with proper environment setup and GitHub-like environment variables
- Action support for various GitHub Actions types
- Output capturing for logs, step outputs, and execution details
- Parallel job execution for faster workflow execution
- Trigger workflows remotely on GitHub/GitLab
- Requirements and usage documentation
**Requirements**
WRKFLW supports multiple container runtimes for isolated execution:
- Docker (default container runtime)
- Podman (a rootless container runtime)
- Emulation (no container runtime required)
**Podman Support**
podman installation (varies by OS):
- macOS with Homebrew: `brew install podman`
- Ubuntu/Debian: `sudo apt-get install podman`
- Initiate Podman machine (macOS/Windows): `podman machine init; podman machine start`
- Use with wrkflw: `wrkflw run --runtime podman .github/workflows/ci.yml`
**Installation**
Recommended to install using Rust's package manager, Cargo:
1. Using Cargo Install (Recommended)
cargo install wrkflw
2. From Source
git clone https://github.com/bahdotsh/wrkflw.git cd wrkflw cargo build --release
The compiled binary will be available at `target/release/wrkflw`
**Usage**
Navigate to your project's root directory and run:
wrkflw
This will automatically detect and load all workflows from `.github/workflows` directory into the TUI interface.
WRKFLW provides three main command modes:
1. Validating Workflow Files
- Validate all workflow files in the default location (`.github/workflows`)
wrkflw validate
- Validate a specific workflow file
wrkflw validate
- Validate workflows in a specific directory
wrkflw validate
- Validate multiple files and/or directories (GitHub and GitLab are auto-detected)
wrkflw validate
- Force GitLab parsing for all provided paths
wrkflw validate --gitlab
- Validate with verbose output
wrkflw validate --verbose
- Validate GitLab CI pipelines
wrkflw validate --gitlab
- Disable exit codes for custom error handling (default: enabled)
wrkflw validate --no-exit-code
**Exit Codes for CI/CD Integration**
- 0: All validations passed successfully
- 1: One or more validation failures detected
- 2: Command usage error (invalid arguments, file not found, etc.)
**Running Workflows in CLI Mode**
- Run a workflow with Docker (default)
wrkflw run .github/workflows/ci.yml
- Run a workflow with Podman instead of Docker
wrkflw run --runtime podman .github/workflows/ci.yml
- Run a workflow in emulation mode (without containers)
wrkflw run --runtime emulation .github/workflows/ci.yml
- Run with verbose output
wrkflw run --verbose .github/workflows/ci.yml
- Preserve failed containers for debugging
wrkflw run --preserve-containers-on-failure .github/workflows/ci.yml
**Using the TUI Interface**
- Open TUI with workflows from the default directory
wrkflw tui
- Open TUI with a specific directory of workflows
wrkflw tui
- Open TUI with a specific workflow pre-selected
wrkflw tui
- Open TUI with Podman runtime
wrkflw tui --runtime podman
- Open TUI in emulation mode
wrkflw tui --runtime emulation
**Triggering Workflows Remotely**
- Trigger a workflow remotely on GitHub
wrkflw trigger --branch --input = --input =
- Trigger a pipeline remotely on GitLab
wrkflw trigger-gitlab --branch --variable = --variable =
**TUI Controls**
The terminal user interface provides an interactive way to manage workflows:
- Tab / 1-4: Switch between tabs (Workflows, Execution, Logs, Help)
- Up/Down or j/k: Navigate lists
- Space: Toggle workflow selection
- Enter: Run selected workflow / View job details
- r: Run all selected workflows
- a: Select all workflows
- n: Deselect all workflows
- e: Cycle through runtime modes (Docker → Podman → Emulation)
- v: Toggle between Execution and Validation mode
- Esc: Back / Exit detailed view
- q: Quit application
**With wrkflw.io**
- All features available on the web platform
- Continuous integration with fine-grained control
- Publish and share your CI/CD setups (style guides, templates)
- Join the public cloud marketplace or create your own cloud platform
**Documentation**
More information, examples, and release notes can be found on the [WRKFLW documentation website](https://bahdotsh.github.io/wrkflw).
**Contributing**
Contributions are always welcome! See the [CONTRIBUTING.md](https://github.com/bahdotsh/wrkflw/CONTRIBUTING.md) file for details on how to contribute.
**License**
This project is licensed under the [MIT License](LICENSE).