local-ci

README

Local CI

Local CI is a tool that allows you to run CI/CD pipelines locally using Docker containers. It helps developers test and debug their CI pipelines without pushing to remote repositories.

Features

• Run CI pipeline jobs locally using Docker
• Stages-based execution similar to GitLab CI
• Configuration using YAML format
• Global and job-specific environment variables
• Working directory customization
• Cache support for dependencies and build artifacts
• Automatic file copying with .gitignore support
• Real-time log streaming from containers
• Automatic container cleanup
• Stage-based pipeline execution
• Job-based pipeline execution
• Parallel job execution (all jobs at once, or per-stage) with a live status board
• Per-job parallel: true keyword for detaching individual jobs from the sequential chain
• Matrix builds: parametrize a job with matrix: to fan it out across variable combinations
• Templates and includes: factor common config into .dot-prefixed templates and pull shared files with include:
• Stage placeholders: splice an included file's stages into the main pipeline at a chosen position
• GitLab utils
• Bootstrap scripts
• Cleanup scripts (companion to bootstrap)
• Per-job bootstrap and cleanup scripts
• Claude Code agent plugin

Installation

Prerequisites

• Docker must be installed and running
• Your user must have permissions to access the Docker daemon
• Verify installation with docker --version

Homebrew (macOS)

brew install --cask MrPuls/local-ci/local-ci

Go Install

Requires Go 1.21 or later (download).

go install github.com/MrPuls/local-ci/cmd/local-ci@latest

Manual

Download the latest binary for your platform from the releases page.

Usage

Check Installation

local-ci --version

Run a Pipeline

# Run using default .local-ci.yaml in current directory
local-ci run

# Run with a specific config file using --config/-c flag
local-ci run --config my-pipeline.yaml

# Run a specific job using --job/-j
local-ci run --job JobName

# Or to run multiple jobs
local-ci run --job jobName1,JobName2

# Run jobs from a specific stage using --stage/-s
local-ci run --stage stageName

# Or use multiple stages
local-ci run --stage stageName1,stageName2

# Run all jobs in parallel with --parallel/-p
local-ci run --parallel

# Or run stages in order, with jobs inside each stage in parallel
local-ci run --parallel-stages

# Clone/update the repository and run it's local-ci.yaml with --remote/-r
local-ci run --remote <repository_url>

# Pass additional environment variables with --env/-e
local-ci run --env NEW_VAR=var_value,SECOND_VAR=new_value

Quick Start

1. Start Docker

2. Create a .local-ci.yaml file in your project root:

stages:
  - build
  - test

variables:
  GLOBAL_VAR: global_value

Build:
  stage: build
  image: golang:1.21
  variables:
    GO_FLAGS: "-v"
  script:
    - echo "Building application..."
    - go build $GO_FLAGS
  cache:
    key: go-build-cache
    paths:
      - .go/
      - build/

Test:
  stage: test
  image: golang:1.21
  script:
    - echo "Testing with global var: $GLOBAL_VAR"
    - go test ./...
  cache:
    key: go-build-cache
    paths:
      - .go/

1. Run the pipeline:

local-ci run

YAML Configuration

Basic Structure

# Define stages and their order
stages:
  - build
  - test
  - deploy

# Global variables (available to all jobs)
variables:
  GLOBAL_KEY: global_value

# Job definitions
job_name:
  stage: build    # Must match one of the defined stages
  image: image_name
  workdir: /path   # Optional
  variables:       # Job-specific variables (override globals)
    KEY: value
  script:
    - command1
    - command2
  cache:           # Optional cache configuration
    key: cache-key
    paths:
      - path/to/cache
      - another/path

Claude Code Agent

Local CI ships as a Claude Code plugin. Once installed, Claude Code can autonomously write pipeline configs, run them, and validate your code in real Docker environments.

Install the plugin

/plugin marketplace add MrPuls/local-ci

/plugin install local-ci@MrPuls-local-ci

See the Technical Reference for details.

Documentation

• YAML Configuration Reference
• Technical Reference
• Claude Code Agent

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License