Run GitHub Actions pipelines locally from the workflow files that already exist in a project.
localci parses .github/workflows/*.yml, normalizes jobs into a DAG, expands matrix jobs, and executes the selected pipeline locally with Docker or a shell backend.
v0.1.0 is an early MVP. It is useful for local smoke tests, parser validation, matrix/DAG debugging, cache/artifact flow checks, and quick CI reproduction experiments.
- GitHub Actions workflow discovery.
- Normalized Pipeline IR for jobs, steps, dependencies, env, matrix, containers, services, and artifacts.
- Matrix expansion with basic
includeandexcludesupport. - DAG scheduling with configurable parallelism via
-j. - Docker backend by default, plus
--backend shellfor fast local tests. --job <name>to run one job and its dependencies.--from <name>to resume from a job and its descendants.- Secret loading from
.localci/secrets.envwith log masking. - Local emulation for
actions/cache. - Local emulation for
actions/upload-artifactandactions/download-artifact. - JSON and JUnit reports.
From source:
cargo install --git https://github.com/dev-toolings/localciOr clone and run:
git clone https://github.com/dev-toolings/localci.git
cd localci
cargo run -- dry-run -C examples/symfony-demoPrint the normalized pipeline without executing it:
localci dry-run -C /path/to/project
localci dry-run -C /path/to/project --format json
localci dry-run -C /path/to/project --format dotRun the full pipeline:
localci run -C /path/to/project -j 4Run one job and its dependencies:
localci run -C /path/to/project --job buildResume from a job and run its descendants:
localci run -C /path/to/project --from testGenerate reports:
localci run -C /path/to/project \
--report-json localci.json \
--report-junit localci.xmlUse the shell backend for fast local smoke tests:
localci run -C /path/to/project --backend shell -j 4Create .localci/secrets.env inside the target project:
API_TOKEN=example-token
DATABASE_URL=postgres://exampleValues loaded from this file are injected into job steps and masked from logs.
Add .localci/secrets.env to the target project's .gitignore.
The repository includes small projects that exercise common CI/CD shapes:
cargo run -- run -C examples/symfony-demo --backend shell -j 2
cargo run -- run -C examples/node-demo --backend shell -j 2
cargo run -- run -C examples/python-demo --backend shell -j 2
cargo run -- run -C examples/rust-demo --backend shell -j 2
cargo run -- run -C examples/go-demo --backend shell -j 2Fixtures included:
examples/symfony-demo: PHP/Composer, Symfony-style layout, lint, tests, matrix job, cache, artifacts.examples/node-demo: Node.js/npm, matrix jobs, cache, package artifact.examples/python-demo: Python, matrix jobs, package artifact.examples/rust-demo: Rust/Cargo, matrix jobs, cache, release artifact.examples/go-demo: Go modules, matrix jobs, cache, binary artifact.
Docker mode is also supported when the workflow declares a Linux container image:
cargo run -- run -C examples/node-demo --backend docker -j 2Supported today:
jobs.<job_id>.needsjobs.<job_id>.runs-onjobs.<job_id>.containerjobs.<job_id>.envjobs.<job_id>.strategy.matrix- job and step
if runstepsusessteps for:actions/checkoutactions/cacheactions/upload-artifactactions/download-artifact
Expression support covers common matrix, env, secrets, github, runner.os, equality, boolean operators, startsWith, and contains cases.
- GitHub Actions is the only provider implemented in v0.1.0.
- Service containers are parsed but not started yet.
- Marketplace actions beyond the built-ins above are skipped by default.
- Use
--strict-actionsto fail on unsupported marketplace actions. - Expression compatibility targets useful local reproduction, not full provider bug compatibility.
diffandreplayare CLI placeholders for future cloud-run comparison and GitHub API replay.
- Start service containers with per-job networking.
- Add marketplace action resolution for composite, Docker, and Node actions.
- Improve GitHub expression parity.
- Add GitLab CI parser support.
- Add TUI and richer logs.
- Add
replay <gh-run-id>and local/cloud diffing.
MIT