Local CI CLI
GitHub Actions workflows run on your machine, and a failing step pauses so the agent can fix the file and retry it.
- 812 ★ on the repository
- Last commit
Extended access
Why this level
- Workflows run in Docker containers with access to the working tree and secrets mounted from `.env.local-ci`.
Install
- Works in
Manual install
npx run-local-ci run --workflow .github/workflows/ci.ymlThe README quick start: no separate install, Docker is required. The agent skill: `npx skills add redwoodjs/local-ci --skill local-ci`.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Workflows run in Docker containers with access to the working tree and secrets mounted from `.env.local-ci`.
This is third-party code. Review the repository files before installing.
What it does
Local CI runs GitHub Actions workflows in Docker on your computer before a commit and push. The project replaces the GitHub server side: the official runner receives jobs from a local API emulator, so `actions/checkout`, `actions/setup-node` and `actions/cache` work unmodified. A run uses the working tree, and no clean commit is needed. When a step fails, the container stays alive with all its state: environment variables, installed tools, intermediate artifacts. Edits on the host sync inside, and only the failed step can be rerun with `npx run-local-ci retry --name <runner-name>`. Package-manager caches live on disk, so reinstalling dependencies takes seconds. For agents there is a `local-ci` skill and a `--json` mode with an NDJSON event stream.
Who it is for. Developers whose GitHub Actions CI fails after a push and whose agent work loses minutes on every verification round.
Good fit when
- A check fails only in CI and every fix attempt means waiting in the cloud.
- The agent has finished and all workflows for the current branch must run before a push.
- Installing dependencies takes minutes and you want a local package cache.
- A failed step should be fixed in place and retried without restarting the whole job.
- A program reads the run results.
Not a fit when
- Docker is not installed and cannot be: containers are required for all jobs.
- You need to replace remote CI itself: Local CI checks beforehand, and GitHub still decides.
- macOS jobs must run on an Intel Mac: support for them is limited to Apple Silicon.
Example request
Run all workflows of the current branch through `local-ci` with pause on failure and fix the failing step without pushing to GitHub.Limitations
A running Docker is required: on macOS OrbStack or Docker Desktop is recommended. Jobs with `runs-on: macos-*` work only on Apple Silicon with `tart` and `sshpass` installed, otherwise they are skipped with an explanation. The default runner comes from the `ghcr.io/actions/actions-runner:latest` image, which has no build tools such as `python3`; add them with your own Dockerfile. The `DOCKER_HOST` variable is ignored, `LOCAL_CI_DOCKER_HOST` is needed. The Rust binary build is not yet part of the npm package. Workflow secrets are read from `.env.local-ci` or the environment. The last commit was made in September 2026.
How to disable. Delete the `local-ci` skill from the agent's skills directory and remove the `npx run-local-ci` call from instructions. Containers of a stopped run and disk caches are removed by hand through Docker.
FAQ
How do I run Local CI?
You need Docker. Then run `npx run-local-ci run --workflow .github/workflows/ci.yml` for one workflow or `npx run-local-ci run --all` to run all those relevant to the current branch.
How do I connect Local CI to an agent?
Run `npx skills add redwoodjs/local-ci --skill local-ci` and add a rule to `CLAUDE.md` or `AGENTS.md` to run the skill before handing over work. The skill fits Claude Code, Cursor, Codex and other agents.
What happens when a step fails?
With `--pause-on-failure` the container stays running. If output does not go to a terminal, the process exits with code 77. Host edits sync inside, then call `retry` with the runner name, optionally with `--from-step <N>`.
How does Local CI differ from Agent CI?
It is the same project after a rename. The `@redwoodjs/agent-ci` package keeps working throughout 0.x and forwards calls, while new settings go into `LOCAL_CI_*`, `.env.local-ci` and `.github/local-ci.Dockerfile`.
Where do workflow secrets come from?
First the `.env.local-ci` file in the repository root, then environment variables with the same name. The token for `secrets.GITHUB_TOKEN` is supplied through the `--github-token` flag.
Discussion
No questions or reviews yet.
Related
CLI toolswrkflw validates and runs GitHub Actions locally, showing job dependencies and logs before changes reach hosted CI.
A gh extension for agentic workflows: describe a task in Markdown and run it with an agent in GitHub Actions
A local gate in front of git push: the branch goes through review, tests, docs and lint in a separate worktree before it reaches the remote with a PR
A GitHub Action that runs Claude Code in pull requests and issues: answers mentions, reviews and makes changes
Nx CLI adopts npm, pnpm or yarn scripts, so teams introduce shared monorepo checks gradually while retaining their commands.
GitHub's official MCP server: code, issues, pull requests, Actions and security alerts straight from the agent
README in short
The README compares Local CI with GitHub Actions and local alternatives on caching, behaviour on failure and the need for a clean commit. Requirements, a flag reference, environment variables, image setup and a section on the agentic dev loop follow.