#StepScope

I Was Tired of Debugging CI/CD Pipelines, So I Built StepScope

how “fix ci”, “fix ci again” and “please work” became three separate commits in my git history

If you’ve worked with GitHub Actions, you’ve probably been here.

You push your code, wait for the workflow to finish, and then… ❌ it fails.

You open the logs hoping to find the issue, but instead you’re scrolling through hundreds of lines of output just to find the one that actually matters. So you make a small change, push again, and wait. Before long, your commit history looks something like this:

• debug ci
• fix ci
• fix ci again
• please work

I’ve been there more times than I’d like to admit — wasting hours waiting on CI, watching my commit history slowly turn into a debugging diary instead of a changelog.

After enough of these cycles, I started asking myself a simpler question: why are we still debugging CI/CD like this? We have real-time dashboards for almost everything else in software — application performance, database queries, distributed traces — yet pipelines are still mostly logs and guesswork.

That question is what led me to build StepScope.

Why CI Debugging Feels So Damn Difficult

Before getting into the fix, it’s worth actually naming why this loop is so painful — because it’s not one big issue, it’s a stack of small ones that compound into genuine dread.

• You’re debugging blind. You have no idea what your workflow will actually do until it’s already running — remotely, on GitHub’s infrastructure, not yours.
• Every iteration costs a commit and a push. There’s no way to just “try again” locally. Every fix attempt means push, wait, watch, repeat.
• Logs are a wall, not a map. GitHub’s log viewer is linear. It doesn’t show you the shape of your pipeline — which jobs ran in parallel, which were skipped, which matrix combination actually broke.
• Secrets are masked exactly when you need them. Reasonable for security, maddening when you’re sure a bad environment variable is your bug and all you see is ***.
• Matrix builds and conditionals are invisible until they aren’t. An if: condition reads fine on paper — until it silently skips the one job you needed, with zero visibility into why.

Put together, debugging a pipeline becomes stressful not because the underlying problems are hard, but because the tools make finding them hard. That was the itch.

The Idea

I wanted to run GitHub Actions locally and actually see what was happening — instead of reading logs after the fact, watch it happen live.

The idea was simple: build a dashboard that shows

• Live pipeline execution
• Job dependency graphs
• Step-by-step logs
• Docker container lifecycle
• Pass, fail, and skipped states, updated in real time

That became the foundation of StepScope: replace terminal-only debugging with a real-time dashboard, before any of it ever touches GitHub’s servers.

How It Works: Teaching a Tool to Understand a Pipeline

To run a workflow locally and visualize it properly, StepScope first has to genuinely understand it — not just execute steps top to bottom, but understand its actual shape.

A GitHub Actions workflow isn’t really a script. It’s a Directed Acyclic Graph (DAG) of jobs, where some depend on others (needs), some run in parallel, and some don't run at all depending on runtime conditions. So that's what StepScope builds internally: a real execution graph, not a linear script runner.

The engine supports:

• Parallel job execution — jobs with no interdependencies actually run concurrently, the same way GitHub’s runners would, so timing issues surface locally instead of only in production.
• Matrix builds — a single job definition can expand into many parallel executions (different OS/Node versions, etc.), each tracked as its own node in the graph.
• Conditional ( if ) evaluation — every condition is evaluated the same way GitHub does, and — importantly — the result is visible on the dashboard. If a job was skipped, you see why, not just that it was skipped.
• GitHub Actions expressions — things like ${{ github.event_name == 'push' }} or ${{ matrix.node-version }} needed a real expression evaluator, not string hacking, so behavior actually matches GitHub's.
• Docker-based isolated runners — each job runs inside its own container, with automatic image management, workspace mounting (your actual repo, including uncommitted changes — the whole point is catching failures before you push), and artifact handling that mirrors how GitHub Actions artifacts work.

Running each job in its own container also means local execution behaves much closer to GitHub’s hosted runners — not a toy simulation of your pipeline, but a real one.

The Dashboard: Where It All Comes Together

The dashboard is powered by WebSockets, streaming execution telemetry to a React frontend as an event-driven system — every job start, step completion, container spin-up, and condition evaluation gets emitted as an event and rendered instantly.

You can watch:

• A live dependency graph, updating as jobs start, finish, and unblock the next ones
• Step-by-step logs, scoped per job — not one giant combined log to scroll through
• Docker containers spinning up, executing, and tearing down
• Secret masking, with visibility into where a secret is used even though the value stays hidden
• Pass, fail, and skipped states for every step, updated the instant they change

Instead of guessing what happened after the fact, you just watch it happen. The first time I saw a matrix build expand into six job nodes on screen, each lighting up green or red in real time, it felt like turning the lights on in a room I’d been debugging in the dark for months.

What I Learned

Building StepScope taught me a lot — and the hardest parts weren’t Docker or React. They were:

• Replicating GitHub Actions’ expression evaluation accurately. The syntax looks simple until you try to match real type coercion rules and context object behavior (github, matrix, needs, env). I rebuilt the evaluator more than once to match real-world behavior instead of just my own test cases.
• Managing container lifecycles reliably, not just in the happy path — stale image caches, orphaned containers from crashed runs, and workspace mount permissions all needed real handling.
• Keeping the live dashboard synchronized with the execution engine. Streaming log lines is the easy 80%. Keeping an entire DAG’s execution state consistent across out-of-order events and reconnects was the harder 20% — the part most “build a live dashboard” tutorials conveniently skip.

Those challenges turned the project into something bigger than a visual dashboard — it became a full local CI/CD execution environment, DAG engine and all.

What’s Next?

StepScope solves one problem today: making CI/CD pipelines visible. The next goal is making them intelligent.

AI-Assisted Debugging

Future versions will go beyond displaying logs. Instead, StepScope will analyze failures, identify likely root causes, and suggest fixes in plain language.

Rather than showing a stack trace, it could explain why a job failed, compare it with previous successful runs, and even recommend the YAML or configuration changes needed to fix the issue.

The vision is simple: spend less time guessing and more time shipping.

Beyond GitHub Actions

Although StepScope currently supports GitHub Actions, the long-term goal is to support multiple CI/CD platforms.

The roadmap includes:

• Jenkins support
• A pluggable parser architecture for GitLab CI, CircleCI, and other pipeline formats
• A unified dashboard that works across different CI systems

No matter which platform you’re using, the mission remains the same: make CI/CD pipelines easier to understand, debug, and improve.

Try It Yourself

StepScope is open source and published on npm. If you’re tired of debugging GitHub Actions purely through logs and vibes, try running one of your own workflows through it — dependency graph, live dashboard, and container-level visibility included, without ever needing to push a commit just to see what your pipeline does.

It’s still evolving, and contributions are genuinely welcome — whether that’s improving expression evaluator coverage, hardening the Docker runner layer, or filing an issue with a workflow pattern that breaks it.

Final Thoughts

StepScope started as a solution to one personal frustration: wasting time waiting for CI failures, and a commit history that looked like a debugging diary instead of a changelog.

Today, it lets me debug workflows locally before pushing code — saving time, and making pipeline debugging something I actually don’t dread anymore.

If you’ve ever had a commit named "fix ci again", you'll probably understand exactly why I built it.

*StepScope is open source and available on npm. Contributions, issues, and feedback are welcome — this is very much a living project, built out of a shared, very universal developer pain. (*GitHub) lets connect (LinkedIn)