Implementation:ClickHouse ClickHouse Praktika CI Framework

Knowledge Sources	ClickHouse
Domains	Development_Process
Last Updated	2026-02-08 00:00 GMT

Overview

Concrete tool for orchestrating ClickHouse's multi-configuration CI/CD pipeline through a custom Python-based framework that manages workflows, jobs, Docker environments, and reporting.

Description

Praktika is a custom CI infrastructure framework developed for ClickHouse. It is implemented as an installable Python package (name: `praktika`, version: `0.1`) that provides a CLI entry point for running CI workflows locally and integrates with GitHub Actions for automated pipeline execution on pull requests.

The framework follows a layered architecture:

• Core module (`ci/praktika/`): Provides generic, reusable CI functionality including workflow orchestration, job scheduling, artifact management, and report generation. This module is intentionally free of ClickHouse-specific logic to enable potential reuse in other projects.
• Workflow definitions (`ci/workflows/`): Declares the structure of CI pipelines as code, specifying which jobs run, in what order, and with what dependencies. Praktika automatically discovers workflow files from this path.
• Project settings (`ci/settings/`): Contains ClickHouse-specific configuration overrides that customize Praktika's default behavior (defined in `ci/praktika/settings.py::_Settings`). Praktika automatically discovers settings from this path.
• Job scripts (`ci/jobs/`): Implements individual build, test, and utility tasks as standalone scripts that Praktika invokes according to the workflow definitions.
• Docker configurations (`ci/docker/`): Contains Dockerfiles and related resources for building container images used across ClickHouse CI jobs, ensuring reproducible build and test environments.
• Definition configs (`ci/defs/`): Contains additional CI configuration files including job configurations, Docker configurations, and other definitions.

The framework integrates with GitHub Actions as its execution platform. When a pull request is created or updated, GitHub Actions triggers Praktika workflows, which schedule and execute jobs, collect results, and post Praktika report links as comments on the pull request.

Usage

Praktika is used in two primary modes:

• Automated CI: Triggered automatically by GitHub Actions on pull request events. No manual intervention required.
• Local execution: Developers can run specific CI workflows or jobs locally using the `praktika` CLI, enabling local reproduction of CI failures.

Code Reference

Source Location

• Repository: ClickHouse
• Documentation: ci/README.md (lines 1-17)
• Package setup: ci/setup.py (lines 1-17)
• Core framework: ci/praktika/ (module directory)
• Workflows: ci/workflows/
• Settings: ci/settings/
• Jobs: ci/jobs/
• Docker: ci/docker/
• Definitions: ci/defs/

Signature

# Package definition (ci/setup.py)
from setuptools import find_packages, setup

setup(
    name="praktika",
    version="0.1",
    packages=find_packages(),
    url="https://github.com/ClickHouse/praktika",
    license="Apache 2.0",
    author="Max Kainov",
    author_email="max.kainov@clickhouse.com",
    description="CI Infrastructure Toolbox",
    entry_points={
        "console_scripts": [
            "praktika=praktika.__main__:main",
        ]
    },
)

CLI Entry Point

# Entry point defined in setup.py
praktika=praktika.__main__:main

I/O Contract

Inputs

Name	Type	Required	Description
Pull request event	GitHub webhook	Yes (automated mode)	A pull request creation or update event triggers the CI pipeline via GitHub Actions
Workflow definitions	Python files in ci/workflows/	Yes	Declare the pipeline structure: which jobs to run, their order, and dependencies
Settings overrides	Python files in ci/settings/	No	Project-specific overrides for Praktika's default settings; overrides values in ci/praktika/settings.py::_Settings
Job scripts	Scripts in ci/jobs/	Yes	Individual task implementations (build, test, utility) that Praktika invokes
Docker images	Dockerfiles in ci/docker/	Yes	Container image definitions used by CI jobs for reproducible environments
Test selectors (local mode)	String	No	When running locally, a selector string specifying which tests or jobs to execute

Outputs

Name	Type	Description
CI status	Pass/Fail	Overall pipeline result indicating whether all required jobs passed
Praktika report links	URLs	Links to detailed HTML reports showing per-test results, posted as comments on the pull request by a CI robot
Build artifacts	Binary files	Compiled ClickHouse binaries for each build configuration (Release, Debug, ASan, TSan, etc.)
Test logs	Log files	Detailed execution logs for each test suite, downloadable as `logs.tar.gz` artifacts
GitHub status checks	Status API	Individual status checks on the PR for each CI job, visible in the GitHub UI

Usage Examples

Running integration tests locally

# From the repository root directory
python -m ci.praktika run "integration" --test <selectors>

Inspecting CI report from a PR

# CI reports are JavaScript-rendered; use the fetch_ci_report.js tool
# Install playwright if needed (one-time setup)
cd /tmp && npm install playwright && npx playwright install chromium

# Fetch and analyze CI report (show only failed tests)
node .claude/tools/fetch_ci_report.js "https://s3.amazonaws.com/clickhouse-test-reports/json.html?..." --failed --links

# Download and extract specific test logs
node .claude/tools/fetch_ci_report.js "https://s3.amazonaws.com/..." --test peak_memory --download-logs
tar -xzf /tmp/ci_logs.tar.gz ci/tmp/pytest_parallel.jsonl

Directory structure overview

ci/
+-- README.md               # Documentation of the CI system
+-- setup.py                # Python package setup for praktika
+-- praktika/               # Core framework module (generic, reusable)
|   +-- __main__.py         # CLI entry point
|   +-- settings.py         # Default settings (_Settings class)
|   +-- ...
+-- workflows/              # Workflow definitions (auto-discovered by praktika)
+-- settings/               # Project-specific settings overrides (auto-discovered)
+-- jobs/                   # Individual job scripts (build, test, utility)
+-- docker/                 # Dockerfiles for CI container images
+-- defs/                   # Additional configuration files

Related Pages

Implements Principle

• Principle:ClickHouse_ClickHouse_CI_Pipeline_Execution

Requires Environment

• Environment:ClickHouse_ClickHouse_CI_Docker_Environment