Nanci

CI pipelines in plain Python. Run them locally. Run them in the cloud. Same engine, zero surprises.

nanci.dev · Demo · Docs · Quickstart

---

Define a pipeline by writing a Python file. A @job decorator turns a function into an isolated Docker container. String literals inside the function body are shell commands.

from nanci import job, autocache, ci
import asyncio

@job(image="python:3.12-slim")
@autocache
async def test():
    await ci.upload("src/", "/app/src")
    await ci.upload("tests/", "/app/tests")
    "cd /app && pip install -e . -q && pytest"

@job(image="node:20")
async def frontend():
    await ci.upload("web/", "/app")
    "cd /app && npm ci && npm run build"

@job
async def pipeline():
    await asyncio.gather(test(), frontend())  # run in parallel

asyncio.run(pipeline())

Run it locally with python nanci_ci.py. Push a commit and the same file runs on a Nanci runner in the cloud. What passes locally will pass in CI.

Why

Most CI tools make you write YAML. Nanci lets you write Python — meaning you get loops, conditionals, functions, imports, and the full language for free. Parallelism is asyncio.gather. Fan-out across environments is a list comprehension. File flow between jobs is a typed function argument.

A few things worth knowing

• @autocache — skip a job automatically when its inputs (source code, uploads, arguments) haven't changed
• Artifacts — pass files between jobs as typed return values instead of relying on shared state
• Any Docker image — @job(image="rust:latest"), @job(image="node:20"), whatever your job needs
• Parallel by default — asyncio.gather(job_a(), job_b()) runs both containers at the same time
• Headless mode — emit structured events so the Nanci server can track live progress and stream logs

Quickstart

pip install nanci

# nanci_ci.py
from nanci import job
import asyncio

@job
async def hello():
    "echo Hello, world!"

asyncio.run(hello())

python nanci_ci.py

Full documentation at nanci.dev.

Repository layout

Directory	What it is
engine/	Core job runner — container lifecycle, file transfers, caching, event emission
runner/	Cloud runner agent that picks up and executes pipeline jobs
server/	API server — organizations, projects, pipeline runs, log storage
webhook_listener/	GitHub webhook receiver that triggers pipeline runs on push/PR
web/	Dashboard UI for viewing runs, logs, and pipeline status
landing/	Marketing site (Astro)