ActDebug

Step-debug GitHub Actions on your machine — nothing leaves your computer.

🌐 actdebug.com · 📦 GitHub

ActDebug is a companion debugger for nektos/act. It does not fork or reimplement act — it wraps the act binary to add breakpoints, step-through execution, container inspect, and expression re-eval.

Tool	Role
act	Run GHA workflows locally in Docker (engine)
ActDebug	Debug those runs like a debugger (UI + API + extension)

See docs/ARCHITECTURE.md for the full layered design.

Quick start

git clone https://github.com/FirstIntegral/actdebug.git
cd actdebug
npm install
npm run install-deps      # downloads act v0.2.89; checks Docker
npm run setup-docker-gui  # install Docker (GUI password prompt)
npm start

Open http://127.0.0.1:3847

1. Click Demo repo or load an example workflow
2. Click Start debugging
3. Use Step / Run all — click ● for breakpoints
4. At pause: Inspect container state, Resume

Terminal

npm run demo    # walkthrough without browser
npm test        # 16 automated tests
npm run spike   # act sentinel feasibility check

VS Code / Cursor extension

# Server must be running (npm start)
cd extensions/vscode
# Open in VS Code → F5 (Extension Development Host)

Commands: ActDebug: Start Debugging Workflow, Step, Inspect State, Open Web UI.

Details: extensions/vscode/README.md

Execution engines

Engine	When	What it does
act + Docker	Docker + act available	Real uses: actions in containers; docker exec inspect
shell	No Docker	Local bash for run: steps; simulates actions

ACTDEBUG_ENGINE=shell npm start   # force shell mode

Bundled act: tools/bin/act (v0.2.89). Attribution: tools/ACT_ATTRIBUTION.md.

Platforms

OS	act + Docker	Shell fallback	Notes
Linux	✅ Best	✅	Primary target (x86_64, arm64)
macOS	✅	✅	Docker Desktop + npm run install-deps
Windows	✅ via WSL2	⚠️	Native: install Docker Desktop; WSL2 recommended for full fidelity

npm run install-deps downloads the correct nektos/act binary for your OS (Linux/macOS tar, Windows zip).

Privacy & security

Full audit: docs/SECURITY.md (threat model, findings, hardening).

• Binds 127.0.0.1 only by default — refuses 0.0.0.0 unless ACTDEBUG_INSECURE_BIND=1 (+ token required)
• Optional ACTDEBUG_TOKEN for API auth (tunnels / insecure bind)
• Third-party uses: actions blocked by default — ACTDEBUG_TRUST_REMOTE_ACTIONS=1 to allow
• No accounts, telemetry, or cloud uploads
• Sessions in-memory only
• File access sandboxed to project folder
• Secrets redacted in API responses

Commands

npm start
npm test
node bin/actdebug.js serve
node bin/actdebug.js test

API (v0.4)

Endpoint	Description
GET /api/health	Engine + act/docker capabilities
POST /api/workflows/parse	Parse YAML + matrix info
POST /api/sessions	Create debug session
POST /api/sessions/:id/step	Run one step
POST /api/sessions/:id/run	Run until breakpoint/failure
POST /api/sessions/:id/breakpoints	Toggle breakpoint
GET /api/sessions/:id/state	Inspect container/workspace
POST /api/sessions/:id/eval	Re-eval ${{ }} expressions
POST /api/sessions/:id/resume	Resume sentinel pause

What's included

Path	What it is
fixtures/demo-repo/	Dummy app + .github/workflows/ci.yml
examples/	ci, failing-step, multi-job, matrix
tools/bin/act	Bundled nektos/act binary
extensions/vscode/	VS Code / Cursor extension
docs/	Architecture, upstream proposals, community templates

Community & upstream

• Architecture — docs/ARCHITECTURE.md
• Proposed act CLI hooks (optional, not required) — docs/UPSTREAM_ACT.md
• awesome-runners listing template — docs/AWESOME_RUNNERS.md
• Contributing — CONTRIBUTING.md

Roadmap

• Sentinel run-until-pause (container stays alive)
• Expression re-eval at breakpoints
• Matrix leg picker
• VS Code / Cursor extension (v0.1 scaffold)
• Extension: breakpoint gutter + steps sidebar
• File upstream act hook proposals
• Publish extension to Marketplace / Open VSX
• Domain deploy — actdebug.com landing live

License

MIT — act is MIT-licensed (nektos/act).