Cigen - Universal CI Configuration Generator

Define your pipeline once in a concise, provider‑agnostic format. CIGen validates it with rich error spans and emits provider‑native configuration (CircleCI today; others next).

Why Cigen?

Provider‑native output

Author once; ship native configs. CIGen compiles your universal spec into production‑ready CircleCI YAML without leaking abstractions.

Strong validation

Schema + data‑level checks with precise error spans. Unknown fields are preserved; invalid states fail fast with actionable messages.

Zero‑boilerplate checkout & cache

Git checkout is optimized (shallow fetch, tag/branch controls, host key scanning). Cache steps are injected automatically when you declare them.

Package install detection

Detects pnpm/yarn/npm/bun, bundler, and pip/pipenv; adds the right install steps with provider‑compatible flags and de‑duplicated execution.

Multi‑arch variants

Generate amd64/arm64 job variants from a single job definition.

Split config at scale

Keep large configs maintainable. Merge files from .cigen/config/* automatically and reuse file groups, jobs, and templates. Split your workflows and jobs into multiple files — CIGen merges them seamlessly.

Principles

• Validate early: schema + semantics with rich spans
• Fail fast: explicit, actionable errors; no silent defaults
• Preserve unknowns: never drop user‑provided data
• Native first: emit provider‑idiomatic configuration
• Minimal boilerplate: declare intent; CIGen injects mechanics

Quick Example

Define your pipeline structure:

.cigen/
├── config.yml                    # Provider and global config
├── config/
│   └── source_file_groups.yml  # Reusable file patterns
├── workflows/
│   └── main/
│       └── jobs/
│           ├── test.yml         # Test job definition
│           └── build.yml        # Build job definition

.cigen/config.yml

provider: circleci

.cigen/config/source_file_groups.yml

source_file_groups:
  nodejs:
    - 'src/**/*.js'
    - 'package.json'
    - 'package-lock.json'

.cigen/workflows/main/jobs/test.yml

image: cimg/node:18.0
source_files: '@nodejs'
packages: node
steps:
  - run: npm test

.cigen/workflows/main/jobs/build.yml

image: cimg/node:18.0
architectures: [amd64, arm64]
requires: [test]
source_files: '@nodejs'
packages: node
steps:
  - run: npm run build

Generate CircleCI configuration:

cigen generate

Results in a .circleci/config.yml with:

• Git checkout
• Optional package installation steps (npm/yarn/pnpm/bun, bundler, etc.)
• Separate jobs for each architecture (build_amd64, build_arm64)

How It Works

1. Describe workflows, jobs, packages, and caches in .cigen/
2. CIGen validates and compiles to provider‑native YAML
3. Your CI runs faster and cleaner with less duplication

Current Status

• CircleCI: supported
• Other providers: planned

Getting Started

1. Install cigen
2. Follow the Quick Start guide
3. Read about cigen’s philosophy
4. Explore configuration options