cikit 0.0.5

CI helper toolkit

cikit

cikit is a lightweight Python toolkit for building reproducible CI/CD pipelines.

It provides reusable building blocks for:

• CI environment handling
• provider abstraction for GitLab and local execution
• command execution
• test execution and coverage reporting
• lint integration with Ruff and Pylint
• Sphinx documentation generation
• artifact management
• badge generation
• project metadata handling
• cikit data and pipeline reporting

The package is designed for projects that want to keep CI logic in Python instead of large shell scripts or complex YAML definitions.

Features

Environment Management

Resolve CI variables from multiple sources:

• operating system environment
• CI provider
• project defaults
• template expansion using ${VAR} syntax

from cikit.env import CiEnvironment, get_env_vars

env = CiEnvironment(get_env_vars())

print(env["PROJECT_ROOT"])
print(env.pipeline_id)

Command Execution

Run external tools with:

• live output streaming
• timeout handling
• structured result objects
• graceful process termination

from cikit.command import run_command

result = run_command(["pytest"])
result.check_returncode()

Lint Integration

Generate machine-readable and human-readable reports from:

• Ruff
• Pylint

Reports can be converted into reStructuredText and published as documentation artifacts.

Testing and Coverage

Built-in helpers for:

• pytest execution
• CTest execution
• JUnit XML generation
• coverage collection
• Cobertura reports
• CI summaries

Documentation Generation

Integrates with Sphinx and automatically publishes:

• generated RST files
• badges
• coverage reports
• build artifacts

Generated content can be included directly in project documentation.

Project Metadata

Read project information from:

• pyproject.toml
• cikit.toml

Generate version files and metadata artifacts from a unified project model.

Cikit Data and Metrics

Optional integration with the cikit data backend allows pipelines to store:

• build results
• quality metrics
• coverage values
• historical trends
• local artifact metadata

This data can be used to generate badges and timeline charts across multiple pipeline runs.

Installation

pip install cikit

or with uv:

uv add cikit

Quick Example

from cikit.command import run_command
from cikit.env import CiEnvironment, get_env_vars
from cikit.logging_utils import setup_logging

setup_logging()

env = CiEnvironment(get_env_vars())

result = run_command(
    ["pytest"],
    cwd=env["PROJECT_ROOT"],
)

result.check_returncode()

Typical Project Structure

project/
├── ci_commands/
├── docs/
├── src/
├── tests/
├── pyproject.toml
└── public/
    ├── artifacts/
    ├── badges/
    └── rst/

CI Command Framework

Projects can define Python-based CI commands in a root-level ci_commands package. The cikit console command discovers these commands automatically and provides shared logging, status handling, environment initialization and error handling.

A minimal command module typically looks like this:

import argparse

from cikit import CiSection
from cikit.ci import run_ci_script


def run(env, status, args: argparse.Namespace):
    """Run command logic."""
    with CiSection("Run custom step", status=status):
        ...


def command(args: argparse.Namespace) -> int:
    """Run command."""
    return run_ci_script("custom", lambda env, status: run(env, status, args), args=args)


def register(subparsers: argparse._SubParsersAction):
    """Register command."""
    parser = subparsers.add_parser("custom", help="Run custom CI step.")
    parser.set_defaults(func=command)

The default logical run name can be overridden globally:

cikit --name custom-run custom

Design Goals

• Pure Python implementation
• CI-provider abstraction
• Reproducible builds
• Local execution without CI infrastructure
• Testability
• Minimal external dependencies
• Sphinx-friendly reporting
• GitLab-oriented, but not GitLab-exclusive

Documentation

The full documentation contains:

• CI environment reference
• command execution API
• CI command framework
• lint reporting
• testing helpers
• coverage reporting
• Sphinx integration
• cikit data integration
• artifact management
• examples and recipes

License

GPL-3.0-or-later