Непрерывная интеграция (CI)

Когда вы отправляете pull request, система непрерывной интеграции (CI) ClickHouse запускает для вашего кода ряд автоматических проверок. Это происходит после того, как мейнтейнер репозитория (кто-то из команды ClickHouse) просмотрит ваш код и добавит к вашему pull request метку can be tested. Результаты проверок отображаются на странице pull request в GitHub, как описано в документации GitHub о проверках. Если какая-либо проверка завершается ошибкой, вам может потребоваться её исправить. На этой странице приведён обзор проверок, с которыми вы можете столкнуться, и того, что можно сделать для их исправления. Если похоже, что сбой проверки не связан с вашими изменениями, это может быть временный сбой или проблема с инфраструктурой. Отправьте пустой коммит в pull request, чтобы перезапустить проверки CI:

git commit --allow-empty
git push

Если вы не уверены, что делать, обратитесь за помощью к мейнтейнеру.

Слияние с master

Проверяет, можно ли слить PR с веткой master. Если нет, проверка завершится с сообщением Cannot fetch mergecommit. Чтобы эта проверка прошла, разрешите конфликт слияния, как описано в документации GitHub, или слейте ветку master в ветку вашего pull request с помощью git.

Проверка документации (Mintlify)

Проверяет документацию Mintlify, внутренние ссылки и якоря, перенаправления, импорты фрагментов и журналы изменений. Ошибки внешних ссылок отображаются как предупреждения. Также отклоняет прямые изменения в сгенерированных разделах и копиях документации, доступных только для чтения. Вместо этого обновляйте структурированную документацию в исходной регистрации; намеренные изменения в сгенерированной документации должны иметь метку pr-autogenerated-docs. Если после изменения документации проверка завершается сбоем, откройте её отчёт и найдите сообщения ERROR и WARNING.

Проверка описания

Проверьте, что описание вашего pull request соответствует шаблону PULL_REQUEST_TEMPLATE.md. Вы должны указать категорию в changelog для вашего изменения (например, Bug Fix) и написать понятное пользователю сообщение с описанием этого изменения для CHANGELOG.md

Docker-образ

Собирает Docker-образы сервера ClickHouse и Keeper, чтобы убедиться, что их сборка проходит корректно.

Тесты официальной библиотеки Docker

Запускаются тесты из официальной библиотеки Docker, чтобы убедиться, что Docker-образ clickhouse/clickhouse-server работает корректно. Чтобы добавить новые тесты, создайте каталог ci/jobs/scripts/docker_server/tests/$test_name и поместите в него скрипт run.sh. Дополнительные сведения о тестах можно найти в документации по скриптам CI-задач.

Проверка маркера

Эта проверка означает, что система CI начала обрабатывать pull request. Статус ‘pending’ означает, что запущены ещё не все проверки. После запуска всех проверок статус изменится на ‘success’.

Проверка стиля

Выполняет различные проверки стиля кодовой базы. Каждая из перечисленных ниже проверок соответствует testname в ci/jobs/check_style.py и может быть запущена отдельно с помощью --test <name> (см. ниже).

cpp

Проверки стиля C++ на основе регулярных выражений с помощью check_cpp.sh. Если проверка завершилась ошибкой, исправьте проблемы со стилем в соответствии с руководством по стилю кода.

whitespace_check

Выявляет двойные пробелы после запятых в C++, если они не используются для выравнивания столбцов.

catch_all

Запрещает catch (...) вне деструкторов, main и точек входа фаззера, где небезопасно подавлять неизвестные исключения.

yamllint

Проверяет YAML-файлы workflow в каталоге .github/ с помощью .yamllint.

xmllint

Проверяет XML-файлы в каталогах tests/ и programs/.

functional_tests_check

Проверяет тесты без сохранения состояния: в запросах с фильтрацией по event_date следует использовать >= yesterday(), а не today() (чтобы избежать нестабильности на границе полуночи), а имена файлов тестов не должны содержать fail.

test_numbers_check

Выявляет большие пропуски в нумерации тестов без сохранения состояния (tests/queries/0_stateless/<NNNNN>_*).

симлинки

Обнаруживает неработающие симлинки в репозитории.

разное

Прочие проверки репозитория через various_checks.sh: запросы к system.query_log / system.parts / etc. должны фильтроваться по currentDatabase, пути ZooKeeper для Replicated*MergeTree должны включать отдельный префикс для каждого теста, каталоги интеграционных тестов должны содержать __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

Эти команды загружают Docker-образ clickhouse/style-test и запускают задачу в контейнерной среде. Никаких дополнительных зависимостей, кроме Python 3 и Docker, не требуется.

Запуск тестов без сохранения состояния

Локально установленный ClickHouse с настройками по умолчанию может подойти для отдельных тестовых сценариев, но не позволяет корректно выполнять все тестовые запросы. В CI для каждой задачи применяется определённая конфигурация ClickHouse (например, хранилище S3, параллельные реплики), и вручную воспроизвести её бывает затруднительно. Чтобы этого избежать, вы можете локально воспроизвести любую задачу CI, используя ту же оркестрацию, что и в CI, — ручная настройка не требуется.

Необходимые условия

Python 3 (только стандартная библиотека)
Docker

При необходимости установите Docker в Ubuntu и войдите в систему заново:

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)". Это задаёт ту же конфигурацию ClickHouse и запускает те же тесты, что и в CI.
Архитектура и тип сборки в имени задачи (например, amd_debug) — это метки, специфичные для CI. При локальном запуске они ни на что не влияют: задача будет использовать тот бинарный файл, который вы указали, и ту архитектуру, на которой вы её запускаете. Имя задачи определяет только конфигурацию ClickHouse и набор тестов (если это не переопределено через --test).
В CI функциональные тесты разделены на батчи для более эффективного использования ресурсов. Например, "Stateless tests (amd_debug, parallel)" и "Stateless tests (amd_debug, sequential)" вместе охватывают весь объём: тесты, безопасные для параллельного запуска, выполняются одновременно, а остальные — последовательно. Такое разделение сокращает общее время CI, максимально используя параллелизм там, где это возможно. Чтобы локально воспроизвести полный набор тестов, запустите оба батча.
Также есть задача CI "Fast test", которая запускает ограниченный набор функциональных тестов для проверки базовой работоспособности ClickHouse. Она использует сборку не со всеми необязательными модулями и позволяет быстрее всего обнаружить регрессии. Её можно запустить локально тем же способом. Поместите бинарный файл ClickHouse в один из стандартных путей поиска (./ci/tmp/clickhouse, ./build/programs/clickhouse или ./clickhouse) — иначе задача сначала попытается собрать ClickHouse:
python -m ci.praktika run "Fast test"

Запуск отдельных тестов в рамках задачи CI

С --test задача подготавливает ту же конфигурацию ClickHouse, что используется в CI, но запускает только выбранные тесты:

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 и вам нужно запустить только определенные тесты, используйте псевдоним functional вместо полного имени задачи:
python -m ci.praktika run functional --test 00001_select1

Дополнительные параметры настройки

--path PATH — пользовательский путь к бинарному файлу ClickHouse. По умолчанию runner ищет в следующем порядке: ./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: Сборки 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) - Быстрая релизная сборка ARM64 без Thin LTO
Build (arm_darwin) - Сборка ARM64 для macOS
Build (arm_v80compat) - Сборка для совместимости с ARMv8.0

Другие архитектуры:

Build (ppc64le) - PowerPC 64-bit Little Endian
Build (riscv64) - 64-разрядная RISC-V
Build (s390x) - 64-разрядная IBM System/390
Build (loongarch64) - 64-разрядная LoongArch
Build (wasm64) - 64-разрядный WebAssembly через Emscripten. Экспериментальная: собирает бинарный файл clickhouse и проверяет, что clickhouse local выполняет запросы в Node.js ≥ 24 (модуль также работает в браузерах, но CI пока этого не проверяет)

Если задача завершается успешно, результаты сборки будут доступны в каталоге <repo_root>/ci/tmp/build. Примечание: Для сборок, не относящихся к категории “Другие архитектуры” (в которой используется кросс-компиляция), архитектура локальной машины должна соответствовать типу сборки, чтобы получить сборку, указанную в BUILD_JOB_NAME.

Пример

Чтобы запустить локальную отладочную сборку:

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

Если описанный выше подход вам не подходит, используйте параметры cmake из журнала сборки и следуйте общей процедуре сборки.

Функциональные тесты без сохранения состояния

Запускает функциональные тесты без сохранения состояния для бинарных файлов ClickHouse, собранных в различных конфигурациях — release, debug, с санитайзерами и т. д. Посмотрите отчет, чтобы понять, какие тесты завершаются ошибкой, а затем воспроизведите сбой локально, как описано здесь. Обратите внимание: для воспроизведения нужно использовать правильную конфигурацию сборки — тест может завершаться ошибкой с AddressSanitizer, но проходить в Debug. Скачайте бинарный файл со страницы CI build checks или соберите его локально.

Интеграционные тесты

Запускает интеграционные тесты.

Проверка валидации исправления ошибки

Проверяет, что либо добавлен новый тест (функциональный или интеграционный), либо есть изменённые тесты, которые завершаются ошибкой при запуске с бинарным файлом, собранным из ветки master. Эта проверка запускается, когда у pull request есть метка “pr-bugfix”.

Стресс-тест

Запускает функциональные тесты без сохранения состояния одновременно с нескольких клиентов, чтобы выявить ошибки, связанные с параллелизмом. Если тест завершается сбоем:

Сначала устраните все остальные сбои тестов;
- Просмотрите отчет, чтобы найти журналы сервера, и проверьте их на наличие возможных причин ошибки.

Проверка совместимости

Проверяет, запускается ли бинарный файл clickhouse в дистрибутивах со старыми версиями libc. Если нет, обратитесь за помощью к мейнтейнеру.

AST-фаззер

Запускает случайно сгенерированные запросы, чтобы выявлять ошибки в программе. Если он завершается сбоем, обратитесь за помощью к мейнтейнеру.

Тесты производительности

Оценивайте изменения в производительности запросов. Это самая длительная проверка, её выполнение занимает чуть менее 6 часов. Отчёт о тестах производительности подробно описан здесь.

Откат регрессий CI

Это не проверка вашего pull request: задача запускается в master каждый час и может откатить уже слитый pull request. Задача берёт сбойные тесты, записанные базой данных CI для master за последние 24 часа, и группирует их по имени теста во всех проверках, где этот тест завершился сбоем. Сбой одного и того же теста в отладочной сборке и сборке tsan считается одним сбоем с одной причиной, которую нужно найти; проверки, в которых он проявился, становятся доказательствами в расследовании: изменение, ломающие тест, обычно ломает его сразу в нескольких сборках. Сбои, не связанные ни с каким тестом, например сбой сборки или задача, превысившая лимит времени, исключаются: на вопрос «почему эта проверка завершается сбоем» нет единственного ответа, который можно было бы откатить. Строки, которые тестовая обвязка записывает обо всём скрипте под именем, похожим на имя теста, например Test script failed или Server died, исключаются по той же причине. Тест, завершившийся сбоем более чем на одном коммите master, передаётся AI-агенту, которому предоставляются репозиторий с полной историей master и доступ к базе данных CI только для чтения; он отвечает на один вопрос: был ли этот сбой внесён недавно слитым pull request и каким именно. У агента нет учётных данных GitHub и возможности их создать — он запускается от имени отдельного непривилегированного пользователя с пустым окружением, а конечные точки облачных учётных данных для этого пользователя заблокированы межсетевым экраном. Агент работает в одноразовом клоне репозитория, а не в checkout задачи, поэтому ни его выводы, ни оставленные им данные не могут попасть в GitHub иначе как через описанные ниже проверки. Порог учитывает коммиты, а не строки со сбоями, поэтому один проблемный коммит, в котором сбой возникает в трёх сборках, всё равно считается одним случаем и не приводит к действиям. Также учитывается режим сбоя: в записанных выводах нормализуются изменчивые части (адреса, временные метки, случайные имена баз данных), а тест, имя которого охватывает две разные причины — регрессию в одном коммите и несвязанный флейк в другом, — не считается повторно сбойным. Поэтому расследование не начинается, пока одна и та же причина не повторится сама по себе. К действию приводит только однозначный ответ. Когда агент с высокой уверенностью сообщает о регрессии, а указанный pull request проходит проверки безопасности (слит в master в течение последних трёх дней, сам не является откатом, ещё не был откатан и откат применяется без конфликтов), задача откатывает его, немедленно сливает откат, не дожидаясь проверок, и открывает черновик pull request с заголовком Reapply "...", повторно вносящий изменение. Вердикт о регрессии должен указывать и pull request, и коммит master, которым он был внесён, и они должны соответствовать друг другу: задача сверяет номер с записью GitHub о коммите слияния, созданном этим pull request, и не предпринимает никаких действий, если они не совпадают. Если сбой уже исчез, ничего не откатывается: после исчезновения сбой остаётся в окне наблюдения ещё целый день, поэтому непосредственно перед откатом задача снова запрашивает базу данных CI. Сбой, отсутствующий в новейших коммитах master, которые были обработаны всеми затронутыми проверками, отмечается как уже исправленный и игнорируется. Новейшие коммиты определяются по собственной истории ветки, а не по времени запуска их проверок: старый коммит, проверка которого началась поздно, не должен считаться свежим свидетельством успешного прохождения. Учитывается отсутствие, а не успешное прохождение, поскольку для большинства случаев, которые расследует эта задача, нет строки об успешном прохождении: логическая ошибка или зависшая проверка записывается под текстом самого сбоя и только в момент его возникновения. Проверка считается обработавшей коммит только тогда, когда её запуск прошёл все тесты: запуск, прерванный на середине — записанный обвязкой как Test script failed или Server died рядом со строками тестов, которые он успел создать, — выполнил некоторые тесты, но не обязательно этот. Поэтому отсутствие упоминания сбоя не является доказательством, в отличие от повторного запуска той же проверки, успешно завершившегося на том же коммите. То, насколько длительное отсутствие считается достаточным, зависит от частоты сбоя: пара чистых коммитов ничего не значит для сбоя, возникающего в одном запуске из ста, поэтому требуется период отсутствия, превышающий самый длинный зафиксированный промежуток между проявлениями этого сбоя. Если на вопрос вообще невозможно ответить — проверка, в которой наблюдался сбой, больше не сообщает о нём под этим именем или история коммитов с начала сбоя длиннее, чем возвращает запрос, — это также записывается, и ничего не откатывается. За один запуск откатывается не более двух pull request. Если ваш pull request был откатан:

В pull request с откатом объясняется, что завершается сбоем и почему изменение сочли причиной. Если атрибуция неверна, сообщите об этом там и верните изменение.
Черновик pull request Reapply "..." содержит ваше изменение без изменений. Исправьте сбой в этой ветке, отметьте pull request как готовый к проверке и дайте ему пройти обычный CI.

Каждое расследование фиксируется в таблице checks_investigated базы данных CI, включая те, которые не приводят ни к какому откату. Значения переносятся из checks в том виде, в каком они были там зафиксированы, поэтому две таблицы можно связать обратно: напрямую по test_name; с помощью has(check_names, check_name) и has(commit_shas, commit_sha) — для столбцов, объединяющих несколько строк checks в массив; а также с помощью offending_pull_request_number = pull_request_number — для pull request, признанного причиной проблемы. Историю того, что проверяла задача, к каким выводам она пришла и что сделала, можно запросить на 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 и выполняется в рамках workflow Hourly. Запуск с параметром --dry-run проверяет и оценивает каждое условие, но ничего не изменяет: не создаёт ни таблицу, ни строки, ни ветку, ни pull request, ни слияние; вместо этого выводятся строки, которые были бы записаны. Отдельный workflow .github/workflows/revert_broken_prs.yml откатывает слияния, выполненные при красном CI соответствующих pull request; оба используют одно и то же имя ветки revert-<pull request number>, поэтому один pull request никогда не откатывается дважды. Откат, запущенный вручную, тоже учитывается: задача не выполняется, если откат уже присутствует в master, существует ветка с именем revert-<pull request number> или revert-<pull request number>-<branch> (такую создаёт кнопка Revert в GitHub) либо если pull request из такой ветки открыт или слит.

​Слияние с master

​Проверка документации (Mintlify)

​Проверка описания

​Docker-образ

​Тесты официальной библиотеки Docker

​Проверка маркера

​Проверка стиля

cpp

whitespace_check

catch_all

yamllint

xmllint

functional_tests_check

test_numbers_check

симлинки

разное

​Запуск задачи проверки стиля локально

​Запуск тестов без сохранения состояния

​Необходимые условия

​Запустите задачу CI локально

​Запуск отдельных тестов в рамках задачи CI

​Дополнительные параметры настройки

​Проверка сборки

​Локальный запуск сборок

​Доступные задачи сборки

​Пример

​Функциональные тесты без сохранения состояния

​Интеграционные тесты

​Проверка валидации исправления ошибки

​Стресс-тест

​Проверка совместимости

​AST-фаззер

​Тесты производительности

​Откат регрессий CI