mirror of
https://github.com/bahdotsh/wrkflw.git
synced 2026-05-18 13:16:04 +02:00
4c0f890ba7
* docs: gut the documentation bloat and remove dead files The documentation had grown into the kind of sprawling mess where the same feature gets explained three times in three different files, none of which agree with each other. The main README alone was 610 lines of duplicated sections, speculative roadmaps, and verbose limitation disclaimers that nobody reads. Remove 12 files that had no business existing: junk test files (hello.cpp, hello.rs, test.py), duplicate agent configs, a 487-line Podman testing manual, unused asciinema recordings, and 7MB of unreferenced GIF files. Merge the useful bits from GITLAB_USAGE.md into the main README where they belong. Rewrite the main README from 610 lines down to ~170. Every feature is mentioned once, in one place, with one example. The crate README now actually lists all 14 crates instead of pretending secrets doesn't exist. Net result: 3,819 lines deleted, 197 added. The documentation now fits in your head, which is the whole point. * docs: update crate READMEs for latest features and trim secrets The crate READMEs were quietly falling behind the actual code. The executor README didn't mention --job, environment file read-back, or job-level container directives. The UI README didn't mention job selection mode or the tui feature flag. The evaluator README didn't mention composite action input cross-checking. Meanwhile, the secrets README was 387 lines of documentation for a crate whose siblings average 25. It had full provider configuration examples, rate limiting docs, input validation specs, and benchmarking instructions — all of which belong in rustdoc, not a README that's supposed to give you a quick overview. Trim secrets to ~80 lines. Update executor, ui, evaluator, and wrkflw READMEs to reflect features from PRs #77-#83.
227 lines
7.2 KiB
Markdown
227 lines
7.2 KiB
Markdown
# WRKFLW
|
|
|
|
[](https://crates.io/crates/wrkflw)
|
|
[](LICENSE)
|
|
[](https://github.com/bahdotsh/wrkflw/actions/workflows/ci.yml)
|
|
[](https://crates.io/crates/wrkflw)
|
|
|
|
A command-line tool for validating and executing GitHub Actions workflows locally. Test your workflows on your machine before pushing to GitHub.
|
|
|
|
|
|
|
|
## Features
|
|
|
|
- **TUI interface** — interactive terminal UI for browsing, running, and monitoring workflows
|
|
- **Workflow validation** — syntax checks, structural validation, and composite action input cross-checking with CI/CD-friendly exit codes
|
|
- **Local execution** — run workflows using Docker, Podman, or emulation mode (no containers)
|
|
- **Job selection** — run individual jobs with `--job` flag or via TUI job selection mode
|
|
- **Job dependency resolution** — automatic ordering based on `needs` with parallel execution of independent jobs
|
|
- **Action support** — Docker container actions, JavaScript actions, composite actions, and local actions
|
|
- **Reusable workflows** — execute caller jobs via `jobs.<id>.uses` (local or `owner/repo/path@ref`)
|
|
- **GitHub context emulation** — environment variables, `GITHUB_OUTPUT`, `GITHUB_ENV`, `GITHUB_PATH`, `GITHUB_STEP_SUMMARY`
|
|
- **Matrix builds** — full support for `include`, `exclude`, `max-parallel`, and `fail-fast`
|
|
- **Secrets management** — multiple providers (env, file, Vault, AWS, Azure, GCP) with masking and encryption
|
|
- **Remote triggering** — trigger `workflow_dispatch` runs on GitHub or GitLab pipelines
|
|
- **GitLab support** — validate and trigger GitLab CI pipelines
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
cargo install wrkflw
|
|
```
|
|
|
|
Or build from source:
|
|
|
|
```bash
|
|
git clone https://github.com/bahdotsh/wrkflw.git
|
|
cd wrkflw
|
|
cargo build --release
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Launch the TUI (auto-detects .github/workflows)
|
|
wrkflw
|
|
|
|
# Validate workflows
|
|
wrkflw validate
|
|
|
|
# Run a workflow
|
|
wrkflw run .github/workflows/ci.yml
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Validation
|
|
|
|
```bash
|
|
# Validate all workflows in .github/workflows
|
|
wrkflw validate
|
|
|
|
# Validate specific files or directories
|
|
wrkflw validate path/to/workflow.yml
|
|
wrkflw validate path/to/workflows/
|
|
|
|
# Validate multiple paths
|
|
wrkflw validate flow-1.yml flow-2.yml path/to/workflows/
|
|
|
|
# GitLab pipelines
|
|
wrkflw validate .gitlab-ci.yml --gitlab
|
|
|
|
# Verbose output
|
|
wrkflw validate --verbose path/to/workflow.yml
|
|
```
|
|
|
|
**Exit codes:** `0` = all valid, `1` = validation failures, `2` = usage error. Use `--no-exit-code` to disable.
|
|
|
|
### Execution
|
|
|
|
```bash
|
|
# Run with Docker (default)
|
|
wrkflw run .github/workflows/ci.yml
|
|
|
|
# Run with Podman
|
|
wrkflw run --runtime podman .github/workflows/ci.yml
|
|
|
|
# Run in emulation mode (no containers)
|
|
wrkflw run --runtime emulation .github/workflows/ci.yml
|
|
|
|
# Run a specific job
|
|
wrkflw run --job build .github/workflows/ci.yml
|
|
|
|
# List jobs in a workflow
|
|
wrkflw run --jobs .github/workflows/ci.yml
|
|
|
|
# Preserve failed containers for debugging
|
|
wrkflw run --preserve-containers-on-failure .github/workflows/ci.yml
|
|
```
|
|
|
|
### TUI
|
|
|
|
```bash
|
|
# Open TUI with default directory
|
|
wrkflw tui
|
|
|
|
# Open with specific runtime
|
|
wrkflw tui --runtime podman
|
|
```
|
|
|
|
**Controls:**
|
|
|
|
| Key | Action |
|
|
|-----|--------|
|
|
| `Tab` / `1-4` | Switch tabs (Workflows, Execution, Logs, Help) |
|
|
| `Up/Down` or `j/k` | Navigate |
|
|
| `Space` | Toggle selection |
|
|
| `Enter` | Run / View details |
|
|
| `r` | Run selected workflows |
|
|
| `a` / `n` | Select all / Deselect all |
|
|
| `e` | Cycle runtime (Docker / Podman / Emulation) |
|
|
| `v` | Toggle Execution / Validation mode |
|
|
| `t` | Trigger remote workflow |
|
|
| `q` / `Esc` | Quit / Back |
|
|
|
|
### Remote Triggering
|
|
|
|
Trigger `workflow_dispatch` events on GitHub or GitLab.
|
|
|
|
```bash
|
|
# GitHub (requires GITHUB_TOKEN env var)
|
|
wrkflw trigger workflow-name --branch main --input key=value
|
|
|
|
# GitLab (requires GITLAB_TOKEN env var)
|
|
wrkflw trigger-gitlab --branch main --variable key=value
|
|
```
|
|
|
|
## Runtime Modes
|
|
|
|
| Mode | Description | Best for |
|
|
|------|-------------|----------|
|
|
| **Docker** (default) | Full container isolation, closest to GitHub runners | Production, CI/CD |
|
|
| **Podman** | Rootless containers, no daemon required | Security-conscious environments |
|
|
| **Emulation** | Runs directly on host, no containers needed | Quick local testing |
|
|
|
|
## Reusable Workflows
|
|
|
|
```yaml
|
|
jobs:
|
|
call-local:
|
|
uses: ./.github/workflows/shared.yml
|
|
|
|
call-remote:
|
|
uses: my-org/my-repo/.github/workflows/shared.yml@v1
|
|
with:
|
|
foo: bar
|
|
secrets:
|
|
token: ${{ secrets.MY_TOKEN }}
|
|
```
|
|
|
|
- Local refs resolve relative to the working directory
|
|
- Remote refs are shallow-cloned at the specified `@ref`
|
|
- `with:` entries become `INPUT_<KEY>` env vars; `secrets:` become `SECRET_<KEY>`
|
|
|
|
**Limitations:** outputs from called workflows are not propagated back; `secrets: inherit` is not supported; private repos for remote `uses:` are not yet supported.
|
|
|
|
## Secrets Management
|
|
|
|
WRKFLW supports GitHub Actions-compatible `${{ secrets.* }}` syntax with multiple providers:
|
|
|
|
```bash
|
|
# Environment variables (simplest)
|
|
export GITHUB_TOKEN="ghp_..."
|
|
wrkflw run .github/workflows/ci.yml
|
|
|
|
# File-based secrets (JSON, YAML, or .env format)
|
|
# Configure in ~/.wrkflw/secrets.yml
|
|
```
|
|
|
|
Supported providers: environment variables, file-based, HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, Google Cloud Secret Manager. See the [secrets demo](examples/secrets-demo/) for detailed examples.
|
|
|
|
## Limitations
|
|
|
|
### Supported
|
|
- Workflow syntax validation with exit codes
|
|
- Job dependency resolution and parallel execution
|
|
- Matrix builds, environment variables, GitHub context
|
|
- Container, JavaScript, composite, and local actions
|
|
- Reusable workflows (caller jobs)
|
|
- Environment files (`GITHUB_OUTPUT`, `GITHUB_ENV`, `GITHUB_PATH`, `GITHUB_STEP_SUMMARY`)
|
|
- TUI and CLI interfaces
|
|
- Container cleanup (even on Ctrl+C)
|
|
|
|
### Not Supported
|
|
- GitHub encrypted secrets and fine-grained permissions
|
|
- `actions/cache` (no persistent cache between runs)
|
|
- Artifact upload/download between jobs
|
|
- Event triggers other than `workflow_dispatch`
|
|
- Windows and macOS runners
|
|
- Job/step timeouts, concurrency, and cancellation
|
|
- Service containers in emulation mode
|
|
- Reusable workflow output propagation (`needs.<id>.outputs.*`)
|
|
|
|
## Project Structure
|
|
|
|
WRKFLW is organized as a Cargo workspace with focused crates:
|
|
|
|
| Crate | Purpose |
|
|
|-------|---------|
|
|
| `wrkflw` | CLI binary and library entry point |
|
|
| `wrkflw-executor` | Workflow execution engine |
|
|
| `wrkflw-parser` | Workflow file parsing and schema validation |
|
|
| `wrkflw-evaluator` | Structural evaluation of workflow files |
|
|
| `wrkflw-validators` | Validation rules for jobs, steps, triggers |
|
|
| `wrkflw-runtime` | Container and emulation runtime abstractions |
|
|
| `wrkflw-ui` | Terminal user interface |
|
|
| `wrkflw-models` | Shared data structures |
|
|
| `wrkflw-matrix` | Matrix expansion utilities |
|
|
| `wrkflw-secrets` | Secrets management with multiple providers |
|
|
| `wrkflw-github` | GitHub API integration |
|
|
| `wrkflw-gitlab` | GitLab API integration |
|
|
| `wrkflw-logging` | In-memory logging for TUI/CLI |
|
|
| `wrkflw-utils` | Shared helpers |
|
|
|
|
## License
|
|
|
|
MIT License - see [LICENSE](LICENSE) for details.
|