Skip to content

ciwalk v0.1.0 — Debug CI locally with pause, inspect, and retry

Latest
Latest

Choose a tag to compare

View all tags
@kiwi-07 kiwi-07 released this 15 Jul 09:47
v0.1.0
42d2a5b
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

First public release of ciwalk — a local GitHub Actions runner that keeps the container alive when something fails, so you can inspect state, fix it, and retry without another commit-push-wait cycle.

Highlights

  • Run workflows locally in Docker — ciwalk run <workflow.yml> with workspace bind-mount (no network clone for actions/checkout)
  • Pause on failure — --pause-on-fail opens an interactive shell in the same container (same env, cwd, and bash flags as the failed step)
  • Breakpoints — --breakpoint / -b to pause before a named step
  • Retry / continue / abort — fix in the shell, then choose what happens next; continue after a failure still exits non-zero
  • Orphan cleanup — ciwalk cleanup and ciwalk cleanup --dry-run for leftover ciwalk-* containers (e.g. after kill -9)
  • Live step output — streamed to stdout while steps run
  • Safer expressions — ${{ inputs.* }} / ${{ env.* }} supported; unknown ${{ }} fails loudly instead of silently becoming empty strings

Install

uv tool install ciwalk
# or: pipx install ciwalk
# or: pip install ciwalk

Requires: Python 3.11+ and a running Docker daemon.

From GitHub (before/alongside PyPI):

uv tool install git+https://github.com/kiwi-07/ciwalk.git

Quick start

ciwalk run examples/broken-ci.yml --pause-on-fail

In the shell after the failure: touch build/MARKER, exit, then choose retry.

MVP scope (intentional limits)

  • Single job per run (--job when the workflow has multiple jobs)
  • runs-on: ubuntu-latest (or omit)
  • Steps: run, name, env, working-directory
  • ${{ inputs.* }} / ${{ env.* }} only — no full github.* / secrets.* expression language yet
  • Reusable workflows, job-level needs: / if:, matrix, secrets, and arbitrary marketplace actions are not supported yet

Default runner image

catthehacker/ubuntu:act-latest (override with --image)

What's included

  • CLI: ciwalk run, ciwalk cleanup
  • Examples: examples/hello.yml, examples/broken-ci.yml
  • Linux smoke CI on Ubuntu (scripts/linux-smoke.sh)
  • README with demo GIF and install docs

Known limitations

  • No secrets, matrix builds, or full GitHub expression support
  • Jobs using reusable workflows or unsupported job keys are skipped with a non-zero exit
  • Linux bind-mount behavior is validated in CI; macOS uses Docker Desktop
Assets 2
Loading