{"id":47290797,"url":"https://github.com/redwoodjs/agent-ci","last_synced_at":"2026-04-18T20:07:05.851Z","repository":{"id":344747564,"uuid":"1153919891","full_name":"redwoodjs/agent-ci","owner":"redwoodjs","description":"Agent-CI is local GitHub Actions for your agents.","archived":false,"fork":false,"pushed_at":"2026-03-31T10:34:40.000Z","size":6753,"stargazers_count":113,"open_issues_count":23,"forks_count":7,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-02T23:45:41.742Z","etag":null,"topics":["act-alternative","ai-agent","ci-cd","developer-experience","devtools","github-actions","local-runner"],"latest_commit_sha":null,"homepage":"https://agent-ci.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/redwoodjs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-09T20:24:25.000Z","updated_at":"2026-04-02T18:14:20.000Z","dependencies_parsed_at":"2026-04-02T11:02:28.715Z","dependency_job_id":null,"html_url":"https://github.com/redwoodjs/agent-ci","commit_stats":null,"previous_names":["redwoodjs/agent-ci"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/redwoodjs/agent-ci","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redwoodjs%2Fagent-ci","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redwoodjs%2Fagent-ci/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redwoodjs%2Fagent-ci/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redwoodjs%2Fagent-ci/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/redwoodjs","download_url":"https://codeload.github.com/redwoodjs/agent-ci/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redwoodjs%2Fagent-ci/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31516839,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T03:10:19.677Z","status":"ssl_error","status_checked_at":"2026-04-07T03:10:13.982Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["act-alternative","ai-agent","ci-cd","developer-experience","devtools","github-actions","local-runner"],"created_at":"2026-03-16T07:20:07.864Z","updated_at":"2026-04-10T14:03:44.460Z","avatar_url":"https://github.com/redwoodjs.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# Agent CI\n\n**Run GitHub Actions on your machine. Caching in ~0 ms. Pause on failure. Let your agent fix it and retry — without pushing.**\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\".docs/marketing/demo.gif\" alt=\"Agent CI demo — pause on failure, fix, retry\" width=\"700\" /\u003e\n\u003c/p\u003e\n\nAgent CI is a ground-up rewrite of the GitHub Actions orchestration layer that runs entirely on your own machine. It doesn't wrap or shim the runner: it **replaces the cloud API** that the official [GitHub Actions Runner](https://github.com/actions/runner) talks to, so the same runner binary that executes your jobs on GitHub.com executes them locally, bit-for-bit.\n\nActions like `actions/checkout`, `actions/setup-node`, and `actions/cache` work out of the box — no patches, no forks, no network calls to GitHub.\n\n---\n\n## Why another local runner?\n\nTraditional CI is a fire-and-forget loop: push → wait → fail → read logs → push again. Every retry pays the **full cost** of a fresh run. Existing \"run actions locally\" tools either re-implement steps in a compatibility layer or require you to maintain a separate config. Agent CI does neither.\n\n|                            | GitHub Actions     | Other local runners      | **Agent CI**                            |\n| -------------------------- | ------------------ | ------------------------ | --------------------------------------- |\n| Runner binary              | Official           | Custom re-implementation | **Official**                            |\n| API layer                  | GitHub.com         | Compatibility shim       | **Full local emulation**                |\n| Cache round-trip           | Network (~seconds) | Varies                   | **~0 ms (bind-mount)**                  |\n| On failure                 | Start over         | Start over               | **Pause → fix → retry the failed step** |\n| Container state on failure | Destroyed          | Destroyed                | **Kept alive**                          |\n| Requires a clean commit    | Yes                | Yes                      | **No — runs against working tree**      |\n\n### ~0 ms caching\n\nAgent CI replaces GitHub's cloud cache with **local bind-mounts**. `node_modules`, the pnpm store, Playwright browsers, and the runner tool cache all live on your host filesystem and are mounted directly into the container — no upload, no download, no tar/untar. The first run warms the cache; every subsequent run starts with hot dependencies instantly.\n\n### Pause on failure\n\nWhen a step fails, Agent CI **pauses** instead of tearing down. The container stays alive with all state intact — environment variables, installed tools, intermediate build artifacts. Your edits on the host are synced into the container, so you (or your AI agent) can fix the issue and **retry just the failed step**. No checkout, no reinstall, no waiting.\n\nThis makes Agent CI ideal for **AI-agent-driven development**: point an agent at the failure, let it fix and retry in a tight loop — without the cost of a full remote CI cycle each time.\n\n### Real GitHub Actions Runner, real compatibility\n\nAgent CI does not re-implement GitHub Actions. It emulates the **server-side API surface** — the Twirp endpoints, the Azure Block Blob artifact protocol, the cache REST API — and feeds jobs to the unmodified, official runner. If your workflow runs on GitHub, it runs here.\n\n---\n\n## Quick start\n\n### Prerequisites\n\n- **Docker** — a running Docker provider:\n  - **macOS:** [OrbStack](https://orbstack.dev/) (recommended) or Docker Desktop\n  - **Linux:** Native Docker Engine\n\n### Install\n\n```bash\nnpm install -D @redwoodjs/agent-ci\n```\n\n### Run\n\n```bash\n# Run a specific workflow\nnpx agent-ci run --workflow .github/workflows/ci.yml\n\n# Run all relevant workflows for the current branch\nnpx agent-ci run --all\n```\n\nAgent CI runs against your **current working tree** — uncommitted changes are included automatically. No need to commit or stash before running.\n\n### Retry a failed step\n\n```bash\nnpx agent-ci retry --name \u003crunner-name\u003e\n```\n\n---\n\n## CLI reference\n\n### `agent-ci run`\n\nRun GitHub Actions workflow jobs locally.\n\n| Flag                       | Short | Description                                                                                                                                                  |\n| -------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `--workflow \u003cpath\u003e`        | `-w`  | Path to the workflow file                                                                                                                                    |\n| `--all`                    | `-a`  | Discover and run all relevant workflows for the current branch                                                                                               |\n| `--pause-on-failure`       | `-p`  | Pause on step failure for interactive debugging                                                                                                              |\n| `--quiet`                  | `-q`  | Suppress animated rendering (also enabled by `AI_AGENT=1`)                                                                                                   |\n| `--no-matrix`              |       | Collapse all matrix combinations into a single job (uses first value of each key)                                                                            |\n| `--github-token [\u003ctoken\u003e]` |       | GitHub token for fetching remote reusable workflows (auto-resolves via `gh auth token` if no value given). Also available as `AGENT_CI_GITHUB_TOKEN` env var |\n| `--commit-status`          |       | Post a GitHub commit status after the run (requires `--github-token`)                                                                                        |\n\n### `agent-ci retry`\n\nRetry a paused runner after fixing the failure.\n\n| Flag              | Short | Description                                   |\n| ----------------- | ----- | --------------------------------------------- |\n| `--name \u003cname\u003e`   | `-n`  | Name of the paused runner to retry (required) |\n| `--from-step \u003cN\u003e` |       | Re-run from step N, skipping earlier steps    |\n| `--from-start`    |       | Re-run all steps from the beginning           |\n\nWithout `--from-step` or `--from-start`, retry re-runs only the failed step (the default).\n\n### `agent-ci abort`\n\nAbort a paused runner and tear down its container.\n\n| Flag            | Short | Description                                   |\n| --------------- | ----- | --------------------------------------------- |\n| `--name \u003cname\u003e` | `-n`  | Name of the paused runner to abort (required) |\n\n### Remote Docker\n\nAgent CI connects to Docker via `DOCKER_HOST`. By default it uses the local socket, but you can point it at any remote daemon:\n\n```bash\nDOCKER_HOST=ssh://user@remote-server npx agent-ci run --workflow .github/workflows/ci.yml\n```\n\n### Docker host resolution for job containers\n\nFor default behavior, env overrides, and remote-daemon caveats, see the CLI package docs:\n\n- [`packages/cli/README.md#docker-host-resolution-for-job-containers`](./packages/cli/README.md#docker-host-resolution-for-job-containers)\n\n---\n\n## Secrets\n\nWorkflow secrets (`${{ secrets.FOO }}`) are resolved in order:\n\n1. **`.env.agent-ci`** file in the repo root (`KEY=VALUE` syntax, `#` comments supported)\n2. **Shell environment variables** — any env var matching a required secret name acts as a fallback\n3. **`--github-token`** — automatically provides `secrets.GITHUB_TOKEN`\n\n```bash\n# All three approaches work:\n# 1. .env.agent-ci file\necho \"CLOUDFLARE_API_TOKEN=xxx\" \u003e\u003e .env.agent-ci\n\n# 2. Inline env vars\nCLOUDFLARE_API_TOKEN=xxx agent-ci run -w .github/workflows/deploy.yml\n\n# 3. --github-token for GITHUB_TOKEN specifically\nagent-ci run -w .github/workflows/ci.yml --github-token\n```\n\n---\n\n## Environment variables\n\nAll configuration is available via environment variables. For persistent machine-local overrides, create a `.env.agent-ci` file in your project root — Agent CI loads it automatically (`KEY=VALUE` syntax, `#` comments supported).\n\n### General\n\n| Variable                | Default                         | Description                                                                                                               |\n| ----------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |\n| `GITHUB_REPO`           | auto-detected from `git remote` | Override the `owner/repo` used when emulating the GitHub API. Useful when the remote URL can't be detected automatically. |\n| `AI_AGENT`              | unset                           | Set to `1` to enable quiet mode (suppress animated rendering). Same effect as `--quiet`.                                  |\n| `DEBUG`                 | unset                           | Enable verbose debug logging. See [Debugging](#debugging) for supported namespaces.                                       |\n| `AGENT_CI_GITHUB_TOKEN` | unset                           | GitHub token for fetching remote reusable workflows. Alternative to the `--github-token` CLI flag.                        |\n\n### Docker\n\n| Variable                                      | Default                             | Description                                                                                           |\n| --------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------- |\n| `DOCKER_HOST`                                 | `unix:///var/run/docker.sock`       | Docker daemon socket or URL. Set to `ssh://user@host` to use a remote daemon.                         |\n| `AGENT_CI_DTU_HOST`                           | `host.docker.internal`              | Hostname or IP that runner containers use to reach the DTU mock server on the host.                   |\n| `AGENT_CI_DOCKER_EXTRA_HOSTS`                 | `host.docker.internal:host-gateway` | Comma-separated `host:ip` entries passed to Docker `ExtraHosts`. Fully replaces the default when set. |\n| `AGENT_CI_DOCKER_HOST_GATEWAY`                | `host-gateway`                      | Override the default `host-gateway` token or IP for the automatic host mapping.                       |\n| `AGENT_CI_DOCKER_DISABLE_DEFAULT_EXTRA_HOSTS` | unset                               | Set to `1` to disable the default `host.docker.internal` mapping.                                     |\n| `AGENT_CI_DOCKER_BRIDGE_GATEWAY`              | auto-detected                       | Fallback gateway IP when Agent CI runs inside Docker and cannot detect its container IP.              |\n\n---\n\n## YAML compatibility\n\nSee [compatibility.md](./packages/cli/compatibility.md) for detailed GitHub Actions workflow syntax support.\n\n## Debugging\n\nSet `DEBUG` to enable verbose logging. It accepts comma-separated glob patterns:\n\n| Value                             | What it shows                 |\n| --------------------------------- | ----------------------------- |\n| `DEBUG=agent-ci:*`                | All debug output              |\n| `DEBUG=agent-ci:cli`              | CLI-level logs only           |\n| `DEBUG=agent-ci:runner`           | Runner/container logs only    |\n| `DEBUG=agent-ci:dtu`              | DTU mock-server logs only     |\n| `DEBUG=agent-ci:boot`             | Boot/startup timing logs only |\n| `DEBUG=agent-ci:cli,agent-ci:dtu` | Multiple namespaces           |\n\n```bash\nDEBUG=agent-ci:* npx agent-ci run --workflow .github/workflows/ci.yml\n```\n\nOutput goes to **stderr**. If `DEBUG` is unset, debug loggers are no-ops with zero overhead.\n\n---\n\n## Using with AI coding agents\n\nAgent CI is designed for AI-agent-driven development loops. Add the following snippet to your project's `CLAUDE.md` (for Claude Code) or `.cursorrules` (for Cursor) so your AI agent automatically discovers and uses agent-ci:\n\n```markdown\n## agent-ci\n\n- Use `npx @redwoodjs/agent-ci run --quiet --workflow .github/workflows/ci.yml` to run CI locally\n- When a step fails, the run pauses automatically. Use `npx @redwoodjs/agent-ci retry --name \u003crunner\u003e` to retry after fixing the failure\n- Do NOT push to trigger remote CI when agent-ci can run it locally — it's instant and free\n- CI was green before you started. Any failure is caused by your changes — do not assume pre-existing failures\n- Use `--no-matrix` to collapse matrix jobs into a single run when you don't need full matrix coverage\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredwoodjs%2Fagent-ci","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fredwoodjs%2Fagent-ci","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredwoodjs%2Fagent-ci/lists"}