Push-and-pray CI is dumb. I built a step debugger for GitHub Actions.

ctrl — Fri, 03 Jul 2026 14:54:59 +0000

You know the loop.

You edit a .yml. You commit. You push. You wait for the runner to spin up. You watch it churn through five green steps and then fail on step six — some path that isn't set, some env var that didn't thread through, a script that behaves differently than you remembered. You tweak one line. Commit. Push. Wait again.

Every iteration of that loop costs you a commit you'll squash later and three-to-five minutes of staring at a log that scrolls on a server you can't touch. The feedback is slow and it's blind: when step six fails, you can't get into the machine at the moment it failed and look around. You just get the corpse in the log.

I got tired of it and built walkflow — a tool that runs your workflow's steps on your own machine, one at a time, and pauses between them so you can inspect, fix, and continue. No commit. No push. No waiting.

What it feels like

$ walkflow
walkflow — .github/workflows/ci.yml · job 'build'

▶ job build — 6 step(s)

┌─ step 1/6: checkout
│  uses: actions/checkout@v4 — not executable in host mode, skipping.

┌─ step 2/6: install deps
│    $ npm ci
│  [enter] run · [s]hell · [k] skip · [q] quit >           # ⏎
│  running in /home/me/app
└─ ok

┌─ step 3/6: run tests
│    $ npm test
│  [enter] run · [s]hell · [k] skip · [q] quit >           # ⏎
FAIL src/auth.test.ts  ✗ token refresh
│  step failed. [r]etry · [s]hell · [c]ontinue · [q]uit >  # s
│  entering shell (/bin/zsh); `exit` to return to walkflow
$ echo $NODE_ENV        # inspect the exact env step 3 saw
test
$ vim src/auth.ts       # fix it right here
$ exit
│  back in walkflow
│  step failed. [r]etry · [s]hell · [c]ontinue · [q]uit >  # r
└─ ok

The important part is the s. When a step fails — or before any step runs — you can drop into a shell in the workspace, with every environment variable the previous steps exported. Not a fresh shell. The exact state that step would have seen: the PATH additions from earlier steps, the values written to $GITHUB_ENV, the working directory. You poke around, figure out what's wrong, fix the file right there, exit, and hit r to retry — and r even offers to open the failing command in $EDITOR first.

The inner loop that used to be "push and pray, wait four minutes" is now seconds long.

"Isn't that what `act` does?"

Sort of, and this is the first question everyone asks, so let me be precise.

act runs your whole workflow locally in Docker. It's great for replaying — top to bottom, start to finish, then it stops. What it doesn't do is pause between steps, drop you into the live intermediate state, or let you edit a failed step and re-run it in place. That's been an open feature request on act for years.

walkflow is built around exactly that missing piece — the interactive inner loop, not the full replay:

	`act`	`walkflow`
Run workflow locally	✅	✅
Pause between steps	❌	✅
Drop into a shell with live step state	❌	✅
Edit a failed step and retry in place	❌	✅
Faithful `$GITHUB_ENV` / `$GITHUB_PATH` threading	✅	✅

They're not really competitors. act answers "does the whole thing pass in a container?" walkflow answers "why is step six broken, and can I fix it without pushing eight times?"

What it faithfully reproduces

I care about this being honest, because a debugger that lies to you is worse than no debugger. walkflow reproduces:

Environment layering: workflow env: → job env: → step env:.
$GITHUB_ENV exports — both KEY=value and the KEY<<EOF heredoc form — threaded into later steps.
$GITHUB_PATH additions prepended to PATH for later steps.
The default step shell (bash --noprofile --norc -eo pipefail), or your shell: override.
$GITHUB_WORKSPACE, $CI, $GITHUB_ACTIONS, per-step working-directory.

What it doesn't (yet) — stated, not hidden

uses: steps (marketplace actions like actions/checkout, actions/setup-node) are skipped with a note. Most are no-ops against your local checkout anyway. Running them with full Docker environment parity is the headline feature on the roadmap.
${{ expressions }} aren't evaluated — steps run with the literal env. if: conditions and matrix are shown, not enforced.

When walkflow hits one of these, it tells you. No silent surprises.

Handy flags

walkflow                       # finds the single workflow under .github/workflows/
walkflow ci.yml --job build    # pick a file and job
walkflow --list                # print jobs and steps, then exit
walkflow --from 4              # auto-run steps 1–3, go interactive from step 4
walkflow --from "run tests"    # ...or select that step by name
walkflow -y                    # run it all, no pausing — a fast local sanity check

--from is the one I reach for most: it fast-forwards through the steps you already trust (accumulating their env correctly) and hands you the controls exactly at the step you're actually debugging.

Install

It's a single Rust binary, no runtime, no daemon:

cargo install --git https://github.com/mrvlyouknowwho/walkflow

MIT licensed. Repo, issues, and roadmap are here: github.com/mrvlyouknowwho/walkflow.

If you live in GitHub Actions and you've ever pushed a commit whose entire message was fix ci (then fix ci again, then pls), I'd genuinely like to know whether this shortens your loop. Issues and reactions welcome.

DEV Community: ctrl