koci 0.1.1

Kodo CI

koci - Universal CI Definition Tool

One CI file to rule them all.

koci is a universal CI definition tool that lets you:

• 🚀 Run CI pipelines locally using Docker/Podman
• 🔄 Export to any platform - GitHub Actions, Jenkins, GitLab CI, and more
• 📦 Start simple, scale up - One file that grows with your project

Why koci?

Every CI platform has its own syntax. When you switch platforms or need to run CI locally, you're stuck rewriting everything. koci solves this with a universal format that:

• Works locally with Docker containers
• Exports to major CI platforms with one command
• Validates your pipeline before you push
• Watches files and auto-runs on changes

Installation

pip install koci

Or install from source:

git clone https://github.com/kodogen/koci.git
cd koci
pip install -e .

Quick Start

1. Create a Pipeline

koci init

This detects your project type (Node.js, Python, Go, etc.) and creates a koci.yml:

version: "1"
name: my-app

stages:
  - build
  - test

jobs:
  install:
    stage: build
    image: node:20-alpine
    steps:
      - run: npm ci
    artifacts:
      paths:
        - node_modules/

  test:
    stage: test
    image: node:20-alpine
    needs: [install]
    steps:
      - run: npm test
    artifacts:
      consume: [install]

2. Validate

koci validate

3. Run Locally

koci run

Run a specific stage:

koci run --stage test

4. Export to CI Platform

# GitHub Actions
koci export github-actions

# Jenkins
koci export jenkins

# GitLab CI
koci export gitlab

Commands

Command	Description
koci init	Create a starter koci.yml
koci validate	Validate pipeline syntax
koci run	Execute pipeline locally
koci run --stage <name>	Run specific stage
koci export <platform>	Export to CI platform
koci watch	Auto-run on file changes
koci visualize	Show pipeline graph
koci info	Show pipeline summary

Pipeline Syntax

Stages & Jobs

stages:
  - build
  - test
  - deploy

jobs:
  compile:
    stage: build
    image: node:20
    steps:
      - run: npm ci
      - run: npm run build

Dependencies

jobs:
  test:
    stage: test
    needs: [compile]  # Wait for compile to finish
    steps:
      - run: npm test

Artifacts

jobs:
  build:
    stage: build
    steps:
      - run: npm run build
    artifacts:
      paths:
        - dist/

  deploy:
    stage: deploy
    needs: [build]
    artifacts:
      consume: [build]  # Get artifacts from build job
    steps:
      - run: ./deploy.sh

Matrix Builds

jobs:
  test:
    stage: test
    matrix:
      node: [18, 20, 22]
      os: [alpine, slim]
    steps:
      - run: npm test

Services

services:
  test:  # Services for the test stage
    - image: postgres:15
      env:
        POSTGRES_PASSWORD: test
    - image: redis:7

jobs:
  integration:
    stage: test
    steps:
      - run: npm run test:integration

Conditions

Simple conditions:

jobs:
  deploy:
    when: branch == 'main'
    steps:
      - run: ./deploy.sh

Complex conditions:

jobs:
  deploy:
    if: ${{ success() && env.DEPLOY_ENABLED == 'true' }}
    steps:
      - run: ./deploy.sh

Export Targets

GitHub Actions

koci export github-actions
# Creates .github/workflows/ci.yml

Jenkins

koci export jenkins
# Creates Jenkinsfile

GitLab CI

koci export gitlab
# Creates .gitlab-ci.yml

Configuration

Secrets

Create .koci.secrets.yml (gitignored):

env:
  AWS_ACCESS_KEY: xxx
  AWS_SECRET_KEY: xxx

Global Environment

env:
  NODE_ENV: production
  CI: "true"

Default Image

defaults:
  image: node:20-alpine
  working_directory: /app

Development

# Setup
make virtualenv
source env/bin/activate

# Run tests
make test

# Run koci
koci --help

Roadmap

• Core pipeline execution
• GitHub Actions export
• Jenkins export
• GitLab CI export
• CircleCI export
• Concourse export
• Azure Pipelines export
• Parallel job execution
• Remote cache support
• Plugin system

License

MIT License - see LICENSE.md