koci 0.1.3

Kodo CI - Universal CI/CD Pipeline Tool

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

Run jobs in parallel (jobs must have parallel: true):

koci run                 # Parallel jobs run together (up to 4)
koci run -p 8            # Up to 8 parallel jobs simultaneously
koci run -p 1            # Force sequential execution

Graceful shutdown with Ctrl+C - containers are cleaned up properly:

koci run                 # Press Ctrl+C once for graceful shutdown
# ⚠ Received SIGINT, shutting down gracefully...
#   (Press Ctrl+C again to force quit)
# Cleaning up resources...
# ✓ Cleanup complete

koci run                 # Press Ctrl+C twice to force quit (no cleanup)
# ⚠ Force quit!

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

Parallel Jobs

Jobs with parallel: true run simultaneously (respecting --parallel limit):

jobs:
  test-unit:
    stage: test
    parallel: true      # Run in parallel with other parallel jobs
    steps:
      - run: npm test

  test-integration:
    stage: test
    parallel: true      # Runs at the same time as test-unit
    steps:
      - run: npm run test:integration

  test-e2e:
    stage: test
    # No parallel: true, runs after parallel jobs complete
    steps:
      - run: npm run test:e2e

Matrix jobs inherit the parallel flag, so all expanded jobs run together.

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

Test Reports

Collect JUnit test results and code coverage metrics:

jobs:
  test:
    stage: test
    image: python:3.12
    steps:
      - run: pytest --junitxml=results.xml --cov=. --cov-report=xml
    reports:
      junit: test-results/*.xml  # Supports glob patterns
      coverage:
        path: coverage.xml
        format: cobertura  # or lcov, auto
        threshold: 80      # Fail if below 80%

Simple form (just paths):

reports:
  junit: results.xml
  coverage: coverage.xml

When running locally, koci displays a summary after job execution:

    ◆ Collecting test reports...
      ✓ Test Results: 42 passed, 2 failed, 1 skipped (3.2s)
      ✓ Coverage: 84.2% lines (threshold: 80%)

When exporting, reports are configured for each platform:

• GitHub Actions: Uses dorny/test-reporter and codecov/codecov-action
• GitLab CI: Configures artifacts.reports.junit and coverage_report
• Jenkins: Adds junit and publishCoverage post steps

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
• Test reports (JUnit, Coverage)
• Parallel job execution
• Graceful shutdown (Ctrl+C)
• CircleCI export
• Concourse export
• Azure Pipelines export
• Remote cache support
• Plugin system

License

Proprietary - see LICENSE.md

Copyright © 2025 Kodo / The Willum Corporation. All Rights Reserved.

• ✅ Free to use (personal, educational, internal business)
• ✅ View and study source code
• ❌ Cannot sell or commercially distribute
• 📝 Must include attribution