cikit 0.0.4

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 (GitLab and local execution)
• command execution
• test execution and coverage reporting
• lint integration (Ruff, Pylint)
• Sphinx documentation generation
• artifact management
• badge generation
• project metadata handling
• build 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

env = CiEnvironment()
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
• 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.

Job Data and Metrics

Optional integration with the JobData backend allows pipelines to store:

• build results
• quality metrics
• coverage values
• historical trends

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.env import CiEnvironment
from cikit.logging_utils import setup_logging
from cikit.command import run_command

setup_logging()

env = CiEnvironment()

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

result.check_returncode()

Typical Project Structure

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

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
• lint reporting
• testing helpers
• Sphinx integration
• JobData integration
• artifact management
• examples and recipes

License

GPL-3.0-or-later