継続的インテグレーション（CI）

プルリクエストを送信すると、ClickHouse の継続的インテグレーション (CI) システムによって、コードに対していくつかの自動チェックが実行されます。これは、リポジトリのメンテナー (ClickHouse チームのメンバー) がコードを確認し、プルリクエストに can be tested ラベルを追加した後に行われます。各チェックの結果は、GitHub の checks ドキュメントで説明されているとおり、GitHub のプルリクエストページに表示されます。チェックが失敗している場合は、修正が必要になることがあります。このページでは、遭遇する可能性のあるチェックの概要と、その修正方法を説明します。チェックの失敗が自分の変更に関係ないように見える場合は、一時的な障害か、インフラストラクチャの問題である可能性があります。空のコミットをプルリクエストに push して、CI チェックを再実行してください。

git commit --allow-empty
git push

どうすればよいかわからない場合は、メンテナーに相談してください。

master へのマージ

PR を master にマージできることを確認します。マージできない場合は、Cannot fetch mergecommit というメッセージが表示されて失敗します。このチェックを修正するには、GitHub のドキュメントに記載されている手順で競合を解消するか、git を使って master ブランチを自分のプルリクエストのブランチにマージしてください。

ドキュメントチェック (Mintlify)

Mintlify のドキュメント、内部リンクとアンカー、リダイレクト、スニペットのインポート、変更履歴を検証します。外部リンクのエラーは警告として報告されます。また、生成済み領域や読み取り専用のドキュメントコピーを直接編集することはできません。代わりに、ソース登録内の構造化ドキュメントを更新してください。意図的に生成されたドキュメントの更新には、pr-autogenerated-docs ラベルを付与する必要があります。ドキュメントの変更後にチェックに失敗した場合は、レポートを開き、ERROR および WARNING メッセージを確認してください。

説明の確認

プルリクエストの説明が、テンプレート PULL_REQUEST_TEMPLATE.md に準拠していることを確認してください。変更には変更履歴のカテゴリ (例: Bug Fix) を指定し、CHANGELOG.md にその変更内容をユーザー向けにわかりやすく記述する必要があります

Docker イメージ

ClickHouse server と Keeper の Docker イメージをビルドし、正しくビルドできることを確認します。

公式 Docker ライブラリのテスト

clickhouse/clickhouse-server Docker イメージが正しく動作することを確認するために、official Docker library のテストを実行します。新しいテストを追加するには、ディレクトリ ci/jobs/scripts/docker_server/tests/$test_name を作成し、その中にスクリプト run.sh を配置します。テストの詳細については、CI jobs scripts documentation を参照してください。

マーカーチェック

このチェックは、CI システムがプルリクエストの処理を開始したことを示します。ステータスが ‘pending’ の場合は、まだすべてのチェックが開始されていないことを示します。すべてのチェックが開始されると、ステータスは ‘success’ に変わります。

スタイルチェック

コードベースに対してさまざまなスタイルチェックを実行します。以下の各サブチェックは、ci/jobs/check_style.py の testname に対応しており、--test <name> を使って個別に実行できます (以下を参照) 。

cpp

check_cpp.sh を使用して、正規表現ベースの C++ スタイルチェックを行います。失敗した場合は、コードスタイルガイドに従ってスタイルの問題を修正してください。

whitespace_check

カラムの位置合わせの一部ではない、C++ でカンマの後にある二重スペースを検出します。

catch_all

不明な例外を握りつぶすのは安全ではないため、デストラクタ、main、および fuzzer のエントリポイント以外での catch (...) を禁止します。

yamllint

.yamllint を使用して、.github/ 配下の YAML ワークフローファイルをチェックします。

xmllint

tests/ と programs/ 配下にある XML ファイルを検証します。

functional_tests_check

stateless tests をチェックします。event_date に対する filter を含む queries では、today() ではなく >= yesterday() を使用する必要があります (深夜前後での不安定さを避けるため) 。また、テストファイル名に fail を含めてはいけません。

test_numbers_check

stateless tests の採番 (tests/queries/0_stateless/<NNNNN>_*) にある大きなギャップを検出します。

シンボリックリンク

リポジトリ内のリンク切れのシンボリックリンクを検出します。

各種

various_checks.sh による各種リポジトリチェック: system.query_log / system.parts / などに対するクエリは currentDatabase でフィルタする必要があり、Replicated*MergeTree の ZooKeeper パスにはテストごとのプレフィックスを含める必要があり、インテグレーションテストのディレクトリには __init__.py が必要で、UTF BOM は不可、ソース/データファイルに実行可能ビットを付けてはならず、サードパーティの docker-compose イメージに :latest タグを使ってはならない、などがあります。

スタイルチェックジョブをローカルで実行する

スタイルチェック ジョブ全体は、Docker コンテナー内で次のようにローカル実行できます。

python -m ci.praktika run "Style check"

特定のチェック (例: cpp チェック) を実行するには:

python -m ci.praktika run "Style check" --test cpp

これらのコマンドは clickhouse/style-test Dockerイメージを取得し、コンテナ化された環境でジョブを実行します。必要なのは Python 3 と Docker のみで、その他の依存関係はありません。

stateless tests を実行する

ローカルにデフォルト設定でインストールした ClickHouse でも、特定のテストケースは動作する場合がありますが、すべてのテストクエリを正しく実行できるわけではありません。CI では、各ジョブで特定の ClickHouse 構成 (例: S3 ストレージ、並列レプリカ) がセットアップされるため、これを手作業で再現するのは煩雑になりがちです。これを避けるには、CI と同じオーケストレーションを使って、任意の CI ジョブをローカルで再現できます。手動で設定する必要はありません。

前提条件

Python 3 (標準ライブラリのみ)
Docker

必要に応じて Ubuntu に Docker をインストールし、再度ログインしてください：

sudo apt-get update
sudo apt-get install docker.io
sudo usermod -aG docker "$USER"
sudo tee /etc/docker/daemon.json <<'EOF'
{
  "ipv6": true,
  "ip6tables": true
}
EOF
sudo systemctl restart docker

CIジョブをローカルで実行する

CIレポートから任意のジョブ名を選択し、ローカルで実行します:

python -m ci.praktika run "<JOB_NAME>"

ジョブ名は、CI レポートに表示されている表記を必ずそのまま引用してください (スペースやカンマが含まれる場合があります) 。例: "Stateless tests (amd_debug, parallel)"。これにより、CI と同じ ClickHouse の設定で、同じテストが実行されます。
ジョブ名に含まれるアーキテクチャとビルドタイプ (例: amd_debug) は、CI 固有のラベルです。ローカルで実行する場合、これらは影響しません。ジョブでは、実行中のアーキテクチャ上で、指定したバイナリがそのまま使われます。ジョブ名が決定するのは、ClickHouse の設定とテストセットだけです (--test で上書きした場合を除く) 。
CI では、リソースをより効率的に使うために、機能テストを複数のバッチに分割しています。たとえば、"Stateless tests (amd_debug, parallel)" と "Stateless tests (amd_debug, sequential)" を合わせると、テスト対象全体をカバーできます。並列実行しても安全なテストは同時実行され、それ以外は順次実行されます。この分割により、可能な限り並列化して CI の合計実行時間を短縮できます。ローカルでテスト対象全体を再現するには、両方のバッチを実行してください。
また、ClickHouse の基本的な機能を確認するために、限定的な範囲の機能テストを実行する "Fast test" CI ジョブもあります。これは、すべてのオプションモジュールを含まないビルドを使用し、リグレッションを最も手早く検出できる方法です。ローカルでも同じ方法で実行できます。ClickHouse バイナリを既定の検索パスのいずれか (./ci/tmp/clickhouse、./build/programs/clickhouse、または ./clickhouse) に配置してください。そうしないと、ジョブはまず ClickHouse のビルドを試みます。
python -m ci.praktika run "Fast test"

CI ジョブ内で特定のテストを実行する

--test を使用すると、ジョブは CI と同一の ClickHouse セットアップを準備し、選択したテストだけを実行します。

python -m ci.praktika run "Stateless tests (amd_debug, parallel)" \
  --test 00001_select1

複数のテスト名を指定できます。

python -m ci.praktika run "Stateless tests (amd_debug, parallel)" \
  --test 00001_select1 00002_log_and_exception_messages_formatting

ヒント: ClickHouse の構成であればどれでも問題なく、特定のテストだけを実行したい場合は、完全な job 名ではなくエイリアス functional を使用してください。
python -m ci.praktika run functional --test 00001_select1

追加のカスタマイズオプション

--path PATH — ClickHouse バイナリへのカスタムパス。デフォルトでは、ランナーは ./ci/tmp/clickhouse、./build/programs/clickhouse、./clickhouse の順に検索します。
--count N — 各テストを N 回繰り返します。
--workers N — マシンの性能に基づいて自動計算される並列ワーカー数を上書きします。

ビルドチェック

以降の手順で使用するため、さまざまな構成でClickHouseをビルドします。

ビルドをローカルで実行する

以下を使用すると、CI に近い環境でビルドをローカル実行できます。

python -m ci.praktika run "<BUILD_JOB_NAME>"

必要なのは Python 3 と Docker だけです。

利用可能なビルドジョブ

ビルドジョブ名は、CI Report に表示される名前と完全に一致します。 AMD64 ビルド:

Build (amd_debug) - シンボル付きデバッグビルド
Build (amd_release) - 最適化されたリリースビルド
Build (amd_asan) - Address Sanitizer ビルド
Build (amd_tsan) - Thread Sanitizer ビルド
Build (amd_msan) - Memory Sanitizer ビルド
Build (amd_ubsan) - Undefined Behavior Sanitizer ビルド
Build (amd_binary) - Thin LTO なしの高速リリースビルド
Build (amd_compat) - 古いシステム向けの互換ビルド
Build (amd_musl) - musl libc を使用したビルド
Build (amd_darwin) - macOS ビルド
Build (amd_freebsd) - FreeBSD ビルド

ARM64 ビルド:

Build (arm_release) - ARM64 向けの最適化リリースビルド
Build (arm_asan) - ARM64 Address Sanitizer ビルド
Build (arm_coverage) - カバレッジ用インストルメンテーションを含む ARM64 ビルド
Build (arm_binary) - Thin LTO なしの ARM64 高速リリースビルド
Build (arm_darwin) - macOS ARM64 ビルド
Build (arm_v80compat) - ARMv8.0 互換ビルド

その他のアーキテクチャ:

Build (ppc64le) - PowerPC 64 ビット Little Endian
Build (riscv64) - RISC-V 64 ビット
Build (s390x) - IBM System/390 64 ビット
Build (loongarch64) - LoongArch 64 ビット
Build (wasm64) - Emscripten 経由の WebAssembly 64 ビット。実験的: clickhouse バイナリをビルドし、Node.js ≥ 24 上で clickhouse local がクエリを実行することを検証します (モジュールはブラウザでも実行されますが、CI ではまだ検証していません)

ジョブが成功すると、ビルド結果は <repo_root>/ci/tmp/build ディレクトリで利用できます。注: 「その他のアーキテクチャ」カテゴリ以外のビルド (クロスコンパイルを使用しないもの) では、BUILD_JOB_NAME で指定したビルドを生成するために、ローカルマシンのアーキテクチャがビルドタイプと一致している必要があります。

例

ローカルでデバッグビルドを実行するには、次のようにします。

python -m ci.praktika run "Build (amd_debug)"

上記の方法でうまくいかない場合は、ビルドログにある cmake オプションを使用し、一般的なビルド手順に従ってください。

stateless 機能テスト

リリース、デバッグ、サニタイザ有効時など、さまざまな構成でビルドされた ClickHouse バイナリに対して、stateless 機能テストを実行します。どのテストが失敗しているかはレポートを確認し、その後、こちらの説明に従ってローカルで再現してください。再現には正しいビルド構成を使う必要がある点に注意してください。たとえば、あるテストは AddressSanitizer では失敗しても、Debug では成功することがあります。バイナリは CI ビルドチェックページからダウンロードするか、ローカルでビルドしてください。プルリクエストでは、名前が selected tests で終わるサニタイザジョブの大半は、テストスイート全体を実行しません。これらのジョブでは、変更に関連するテストのみを実行します。具体的には、プルリクエストで追加または変更されたテスト、このプルリクエストですでに失敗したテスト、およびカバレッジデータベースに基づいて変更された行を対象とするテストです。既存の Wasm UDF テストが MSan と互換性がないため、MSan/WasmEdge ジョブでは引き続きスイート全体を実行します。デバッグおよびプレーンバイナリ構成でもスイート全体が実行され、サニタイザ有効ビルドはストレステストでテストされ、master ブランチではすべての構成でスイート全体が実行されます。

結合テスト

結合テストを実行します。

バグ修正の validate チェック

新しいテスト (functional またはインテグレーション) が追加されているか、または master ブランチでビルドされたバイナリで失敗するように変更されたテストがあることを確認するチェックです。このチェックは、プルリクエストに “pr-bugfix” ラベルが付いている場合にトリガーされます。

ストレステスト

複数のクライアントからステートレスな機能テストを同時実行し、同時実行に起因するエラーを検出します。失敗した場合:

まず、他のすべてのテスト失敗を修正してください。
- レポートを確認してサーバーログを見つけ、エラーの原因となりそうな点がないか確認してください。

互換性チェック

clickhouse バイナリが古い libc バージョンの Linux ディストリビューション上で実行できることを確認します。失敗した場合は、メンテナーに相談してください。

AST fuzzer

プログラムのエラーを見つけるために、ランダムに生成されたクエリを実行します。失敗した場合は、メンテナーに सहायताを求めてください。

パフォーマンステスト

クエリパフォーマンスの変化を測定します。これは最も時間のかかるチェックで、実行には 6 時間弱かかります。パフォーマンステストレポートの詳細については、こちらを参照してください。

CIのリグレッションをリバートする

これはプルリクエストに対するチェックではありません。master で毎時実行され、すでにマージされたプルリクエストをリバートする場合があります。このジョブは、CI データベースが過去24時間に master に対して記録した失敗テストを取得し、そのテストが失敗したすべてのチェックにわたってテスト名ごとにグループ化します。同じテストが debug ビルドと tsan ビルドで失敗している場合、調査すべき原因は1つの失敗とみなされ、失敗が発生したチェックは証拠として調査対象に含められます。通常、テストを壊す変更は複数のビルドを同時に壊します。ビルド失敗やタイムアウトしたジョブなど、どのテストにも紐付けられない失敗は除外されます。「なぜこのチェックが失敗するのか」には、リバートすべき単一の原因がないためです。 Test script failed や Server died など、テストハーネスがテストのような名前でスクリプト全体について書き込む行も、同様に除外されます。複数の master コミットで失敗したテストは AI エージェントに渡されます。このエージェントには master の完全な履歴を持つリポジトリと CI データベースへの読み取り専用アクセスが与えられ、1つの質問に答えます。この失敗は最近マージされたプルリクエストによって導入されたものか、導入されたならどれか、という質問です。エージェントは GitHub の認証情報を持たず、それを取得する手段もありません。空の環境を持つ独自の非特権ユーザーとして実行され、そのユーザーからはクラウド認証情報エンドポイントがファイアウォールで遮断されています。また、ジョブ自身の checkout ではなく使い捨てのリポジトリクローンで作業するため、エージェントの結論も、残された可能性のあるものも、以下のチェック以外を経由して GitHub に到達することはできません。しきい値では失敗行数ではなくコミット数を数えるため、3つのビルドで失敗する1つの問題のあるコミットも1回の発生として扱われ、対処されません。また、失敗モードごとにも数えます。記録された出力は、変動する部分 (アドレス、timestamp、ランダムなデータベース名) を正規化してフィンガープリント化されます。そのため、テスト名が2つの異なる原因にまたがる場合、つまりあるコミットでのリグレッションと別のコミットでの無関係なフレークがある場合は、繰り返し発生した失敗とは見なされません。したがって、1つの原因が単独で繰り返されるまで何も調査されません。曖昧さのない回答が得られた場合にのみ、アクションが実行されます。エージェントが高い確信度でリグレッションを報告し、指定されたプルリクエストが安全性チェック (過去3日以内に master にマージされていること、自身がリバートではないこと、まだリバートされていないこと、リバートが問題なく適用できること) に合格した場合、ジョブはそれをリバートし、チェックを待たずにリバートを直ちにマージし、変更を再導入する Reapply "..." というタイトルのドラフトプルリクエストを作成します。リグレッションの判定では、プルリクエストと、それが導入された master コミットの両方を指定する必要があり、この2つは一致していなければなりません。ジョブはプルリクエスト番号を、そのプルリクエストが生成したマージコミットに関する GitHub の記録と照合し、一致しない場合はどちらに対しても処理を行いません。失敗が解消された後は何もリバートされません。失敗は解消後も丸1日観測ウィンドウに残るため、リバートの直前にジョブは CI データベースへ再度問い合わせます。そして、影響を受けたすべてのチェックで実行された最新の master コミットに失敗が存在しない場合、すでに修正済みとして記録され、そのままにされます。ここでいう最新コミットは、チェックの実行時刻ではなくブランチ自身の履歴に基づくものです。チェックの開始が遅れた古いコミットを、新しい成功の証拠と見なしてはなりません。合格ではなく不在を確認するのは、このジョブが調査するものの大半には見つけられる合格行がないためです。論理エラーやハングしたチェックは失敗そのもののテキストで記録され、発生したときにのみ記録されます。チェックがコミットを実行したと見なされるのは、その実行がテストを完了した場合のみです。途中で中断された実行は、ハーネスによって生成されたテスト行の隣に Test script failed または Server died と記録されますが、これは 一部の テストを実行したに過ぎず、必ずしもこのテストを実行したとは限りません。そのため、その失敗について記録がないことは証拠になりません。一方、同じコミットで完了した同じチェックの再実行は証拠になります。どの程度の不在を数えるかは、失敗の発生頻度によって異なります。100回の実行のうち1回失敗するものにとって、数回のクリーンなコミットは意味がありません。そのため、要件は、その失敗が自らの発生間で記録上途切れていた最長期間を超えることです。質問にまったく答えられない場合、たとえば失敗が確認されたチェックがその名前で報告しなくなった場合や、失敗開始以降のコミット履歴がクエリの返却範囲より長い場合も、そのことが記録され、何もリバートされません。 1回の実行でリバートされるプルリクエストは最大2件です。プルリクエストがリバートされた場合:

リバート用プルリクエストには、何が失敗しているか、なぜその変更が原因と判断されたかが説明されています。原因の特定が誤っている場合は、そこでその旨を伝え、変更を復活させてください。
Reapply "..." ドラフトプルリクエストには、変更がそのまま保持されています。そのブランチで失敗を修正し、レビュー可能な状態にして、通常の CI を通してください。

すべての調査は、何もリバートしなかったものも含めて、CI データベースの checks_investigated テーブルに記録されます。値は checks に記録されたとおりに引き継がれるため、2 つのテーブルは再度結合できます。具体的には、test_name は直接使用し、複数の checks 行を配列にまとめるカラムには has(check_names, check_name) と has(commit_shas, commit_sha) を使用し、原因となったプルリクエストには offending_pull_request_number = pull_request_number を使用します。ジョブが何を調査し、どのような結論に至り、何を実行したかの履歴は、play.clickhouse.com でクエリできます。

SELECT investigation_time, test_name, check_names, failure_count, commit_count, verdict, confidence, action, explanation
FROM checks_investigated
WHERE investigation_time >= now() - INTERVAL 7 DAY
ORDER BY investigation_time DESC;

このジョブは ci/jobs/revert_ci_regressions.py に実装されており、Hourly ワークフローの一部として実行されます。 --dry-run を指定して実行すると、すべてのガードを調査・評価しますが、何も変更しません。テーブル、行、ブランチ、プルリクエスト、マージは作成せず、書き込むはずだった行を代わりに出力します。別のワークフロー .github/workflows/revert_broken_prs.yml は、自身の CI が失敗している状態でマージされた変更をリバートします。どちらも同じ revert-<pull request number> というブランチ名を使用するため、プルリクエストが二度リバートされることはありません。手動で開始したリバートも考慮されます。リバートがすでに master に存在する場合、revert-<pull request number> または revert-<pull request number>-<branch> (GitHub の Revert ボタンで作成されるブランチ) という名前のブランチが存在する場合、またはそのようなブランチからのプルリクエストがオープン中またはマージ済みの場合、ジョブは処理を行いません。

​master へのマージ

​ドキュメントチェック (Mintlify)

​説明の確認

​Docker イメージ

​公式 Docker ライブラリのテスト

​マーカーチェック

​スタイルチェック

cpp

whitespace_check

catch_all

yamllint

xmllint

functional_tests_check

test_numbers_check

シンボリックリンク

各種

​スタイルチェックジョブをローカルで実行する

​stateless tests を実行する

​前提条件

​CIジョブをローカルで実行する

​CI ジョブ内で特定のテストを実行する

​追加のカスタマイズオプション

​ビルドチェック

​ビルドをローカルで実行する

​利用可能なビルドジョブ

​例

​stateless 機能テスト

​結合テスト

​バグ修正の validate チェック

​ストレステスト

​互換性チェック

​AST fuzzer

​パフォーマンステスト

​CIのリグレッションをリバートする