Local CI

Run GitHub Actions workflows locally using Docker and act. Validate CI in about a minute on your machine instead of waiting for remote runners.

Summary

Local CI parses your workflow file, runs selected jobs in containers with pre-built images, and uses caching (ccache, Boost, CMake, APT) to keep runs fast. It is designed for projects like Boost.Capy but works with any GitHub Actions workflow that uses Linux containers.

Features

• Workflow analysis — Inspect jobs and matrix from any .yml workflow
• Local execution — Run jobs via act with configurable parallelism
• Caching — ccache, Boost clone, B2 build dir, CMake config, and APT package cache
• Pre-built images — Use or build Docker images per compiler/OS to avoid repeated setup
• MCP server — Optional Model Context Protocol interface for AI/IDE integration

Prerequisites

Tool	Purpose
Python 3.10+	CLI runtime
Docker	Container execution
mikefarah/yq v4+	YAML parsing -- not pip yq (PyPI) or kislyuk/yq
act	Run GitHub Actions locally

yq (mikefarah/yq v4 or newer)

Several incompatible tools share the name yq. Local CI requires mikefarah/yq v4+ (yq --version output should reference mikefarah / github.com/mikefarah or report version v4). The wrong install fails at runtime with unclear errors. If no suitable binary is on PATH, the CLI uses a PyYAML fallback with limited expression support and emits a warning.

OS	Example install
Windows	winget install MikeFarah.yq or choco install yq — or a binary from Releases
macOS	brew install yq
Linux	sudo snap install yq or install the static binary from Releases (verify with yq --version before relying on a distro package)

More options: mikefarah/yq — Install.

Installation

cd cli/
pip install .

For editable install (development):

cd cli/
pip install -e ".[dev]"

Quick Start

# From your project root (where .github/workflows/ lives)
cd my-project/

# Create config (optional)
localci config init

# See what the workflow does
localci analyze .github/workflows/ci.yml

# List jobs (e.g. Linux only)
localci list --platform linux

# Dry run
localci run --platform linux --dry-run

# Run
localci run --platform linux

Usage

Command	Description
localci analyze <workflow>	Parse and show jobs/matrix
localci list	List available jobs (optional filters)
localci run	Execute selected jobs
localci status	Show run progress
localci logs <job>	View job logs
localci images	List/build Docker images
localci cache	Clear or inspect caches
localci config	Show/edit .localci.yml

Configuration is read from .localci.yml in the project root (see User Guide for full options).

Project Layout

local-ci-test-system/
├── cli/                 # localci Python package and CLI
│   ├── localci/         # Source
│   └── Usage Guide.md   # Full usage and config reference
├── docs/                # Design and planning
│   ├── Design Guide.md
│   └── Preparation and Plan.md   # Issue breakdown and roadmap
├── images/              # Docker image build scripts (e.g. capy)
└── README.md            # This file

Documentation

• User Guide — Installation, configuration, commands, troubleshooting
• Design Guide — Architecture, MCP, caching
• Performance and Caching — Cache layout and config
• Preparation and Plan — Implementation plan and issue breakdown

License

BSL-1.0 (see LICENSE).