By name: agent-ci description: Run GitHub Actions workflows locally with pause-on-failure for AI-agent-driven CI iteration keywords: [github-actions, local-ci, pause-on-failure, ai-agent, runner]
What agent-ci does
Runs the official GitHub Actions runner binary locally (in Docker), emulating GitHub's cloud API. Cache is bind-mounted (instant). When a step fails, the container pauses — you can fix and retry the failed step without restarting.
When to use agent-ci (not act)
- You want bit-for-bit compatibility with remote GitHub Actions
- You need pause-on-failure for AI agent debugging loops
- Cache round-trip speed matters
Key commands
- Run workflow:
npx @redwoodjs/agent-ci run --workflow <path> - Run all relevant workflows (those whose
ontriggers match the current branch/event, just like GitHub):npx @redwoodjs/agent-ci run --all - Retry after fix:
npx @redwoodjs/agent-ci retry --name <runner> - Abort:
npx @redwoodjs/agent-ci abort --name <runner>
Agent output mode
Pass --json (or set AGENT_CI_JSON=1) to emit an NDJSON event stream on stdout — one JSON object per line, with run.start/paused/finish, job.start/finish, step.start/finish, and diagnostic events. run.start carries schemaVersion: 1. Pair with --pause-on-failure: when stdout isn't a TTY the launcher detaches and the foreground process exits 77 the instant a run.paused event fires, so callers can react cleanly without parsing plaintext.
Common mistakes
- Don't push to remote CI to test changes — use
npx @redwoodjs/agent-ci runlocally first - Don't use
--from-startwhen only the last step failed — useretrywith no flags to re-run only the failed step - The
AI_AGENT=1env variable disables animated output for cleaner agent logs - Use
--no-matrixto collapse matrix jobs into a single run — your local machine is likely faster than GitHub's runners, so parallelizing across matrix combinations is unnecessary