Integración continua (CI)

Descripción general del sistema de integración continua de ClickHouse

Cuando envías un pull request, el sistema de integración continua (CI) de ClickHouse ejecuta algunas comprobaciones automatizadas sobre tu código. Esto ocurre después de que un responsable del repositorio (alguien del equipo de ClickHouse) haya revisado tu código y haya añadido la etiqueta can be tested a tu pull request. Los resultados de las comprobaciones aparecen en la página del pull request de GitHub, como se describe en la documentación sobre comprobaciones de GitHub. Si una comprobación falla, puede que tengas que corregirla. Esta página ofrece una descripción general de las comprobaciones con las que te puedes encontrar y de lo que puedes hacer para corregirlas.

Si parece que el fallo de la comprobación no está relacionado con tus cambios, puede tratarse de un fallo transitorio o de un problema de infraestructura. Haz push de un commit vacío al pull request para reiniciar las comprobaciones de CI:

git commit --allow-empty
git push

Si no estás seguro de qué hacer, pide ayuda a un responsable del proyecto.

​

Fusionar con master

Verifica que la PR pueda fusionarse con master. Si no es así, fallará con el mensaje Cannot fetch mergecommit. Para corregir esta comprobación, resuelve el conflicto como se describe en la documentación de GitHub, o fusiona la rama master en la rama de tu pull request usando git.

​

Comprobación de la documentación (Mintlify)

Valida la documentación de Mintlify, los enlaces internos y las anclas, las redirecciones, las importaciones de fragmentos y los changelogs. Los fallos en enlaces externos se notifican como advertencias. También rechaza las ediciones directas de secciones generadas y de copias de documentación de solo lectura. Actualiza en su lugar la documentación estructurada en el registro de origen; las actualizaciones intencionadas de contenido generado deben llevar la etiqueta pr-autogenerated-docs. Si la comprobación falla después de un cambio en la documentación, abre el informe y busca los mensajes ERROR y WARNING.

​

Comprobación de la descripción

Comprueba que la descripción de tu pull request se ajuste a la plantilla PULL_REQUEST_TEMPLATE.md. Tienes que especificar una categoría del changelog para tu cambio (por ejemplo, Corrección de errores) y escribir un mensaje claro para el usuario que describa el cambio para CHANGELOG.md

​

Imagen de Docker

Compila las imágenes de Docker del servidor de ClickHouse y de Keeper para verificar que se compilan correctamente.

​

Pruebas oficiales de la biblioteca de Docker

Ejecuta las pruebas de la biblioteca oficial de Docker para verificar que la imagen de Docker clickhouse/clickhouse-server funcione correctamente.

Para añadir nuevas pruebas, crea un directorio ci/jobs/scripts/docker_server/tests/$test_name y el script run.sh allí.

Puedes encontrar más detalles sobre las pruebas en la documentación de los scripts de jobs de CI.

​

Comprobación de marcador

Esta comprobación significa que el sistema de CI ha comenzado a procesar el pull request. Cuando tiene el estado ‘pending’, significa que aún no se han iniciado todas las comprobaciones. Una vez iniciadas todas las comprobaciones, el estado cambia a ‘success’.

​

Comprobación de estilo

Realiza varias comprobaciones de estilo en la base de código. Cada una de las subcomprobaciones que se indican a continuación corresponde a un testname en ci/jobs/check_style.py y puede ejecutarse individualmente con --test <name> (véase más abajo).

cpp

Comprobaciones del estilo de C++ basadas en expresiones regulares mediante check_cpp.sh. Si falla, corrige los problemas de estilo según la guía de estilo de código.

whitespace_check

Marca los espacios dobles después de las comas en C++ que no forman parte de la alineación de columnas.

catch_all

Prohíbe catch (...) fuera de los destructores, main y los puntos de entrada del fuzzer, donde no es seguro ignorar una excepción desconocida.

yamllint

Comprueba los archivos YAML de flujo de trabajo en .github/ con .yamllint.

xmllint

Valida los archivos XML en tests/ y programs/.

functional_tests_check

Verifica las pruebas sin estado: las consultas que filtran por event_date deben usar >= yesterday() en lugar de today() (para evitar comportamientos inestables alrededor de la medianoche), y los nombres de los archivos de prueba no deben contener fail.

test_numbers_check

Detecta grandes huecos en la numeración de las pruebas sin estado (tests/queries/0_stateless/<NNNNN>_*).

enlaces simbólicos

Detecta enlaces simbólicos rotos en el repositorio.

varios

Comprobaciones varias del repositorio mediante various_checks.sh: las consultas sobre system.query_log / system.parts / etc. deben filtrar por currentDatabase, las rutas de ZooKeeper de Replicated*MergeTree deben incluir un prefijo específico para cada prueba, los directorios de pruebas de integración deben tener __init__.py, no debe haber BOM UTF, los archivos fuente o de datos no deben tener bits de ejecución, no debe haber tags :latest en imágenes de Docker Compose de terceros, entre otras comprobaciones.

​

Ejecutar localmente el job de comprobación de estilo

El job completo de Style Check puede ejecutarse localmente en un contenedor Docker con:

python -m ci.praktika run "Style check"

Para ejecutar una comprobación específica (p. ej., la comprobación cpp):

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

Estos comandos descargan la imagen de Docker clickhouse/style-test y ejecutan el job en un entorno contenerizado. No se requieren dependencias aparte de Python 3 y Docker.

​

Ejecución de pruebas sin estado

Una instalación local de ClickHouse con la configuración predeterminada puede funcionar para algunos casos de prueba concretos, pero no puede ejecutar correctamente todas las consultas de prueba. En CI, cada job instala una configuración específica de ClickHouse (por ejemplo, almacenamiento S3 o réplicas paralelas), lo que puede ser engorroso de reproducir manualmente. Para evitarlo, puedes reproducir cualquier job de CI en local usando la misma orquestación que en CI, sin necesidad de configuración manual.

​

Requisitos previos

• Python 3 (solo la biblioteca estándar)
• Docker

Instala Docker en Ubuntu si es necesario y vuelve a iniciar sesión:

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

​

Ejecutar un job de CI localmente

Elige el nombre de cualquier job de un informe de CI y ejecútalo localmente:

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

• Pon siempre entre comillas el nombre del job exactamente como aparece en el informe de CI (puede contener espacios y comas), p. ej.: "Stateless tests (amd_debug, parallel)". Esto aplica la misma configuración de ClickHouse y ejecuta las mismas pruebas que en CI.
• La arquitectura y el tipo de compilación del nombre del job (p. ej., amd_debug) son etiquetas específicas de CI. Al ejecutarlo localmente, no tienen ningún efecto: el job usará el binario que proporciones, en la arquitectura en la que lo estés ejecutando. El nombre del job solo determina la configuración de ClickHouse y el conjunto de pruebas (salvo que se sobrescriba con --test).
• En CI, las pruebas funcionales se dividen en lotes para aprovechar mejor los recursos. Por ejemplo, "Stateless tests (amd_debug, parallel)" y "Stateless tests (amd_debug, sequential)" cubren conjuntamente todo el alcance: las pruebas seguras para ejecutarse en paralelo se ejecutan de forma concurrente, y el resto se ejecuta de forma secuencial. Esta división reduce el tiempo total de CI al maximizar el paralelismo siempre que sea posible. Para reproducir localmente todo el alcance de las pruebas, ejecuta ambos lotes.
• También hay un job de CI "Fast test" que ejecuta un conjunto limitado de pruebas funcionales para verificar la funcionalidad básica de ClickHouse: usa una compilación sin todos los módulos opcionales y es la forma más rápida de detectar regresiones. Puedes ejecutarlo localmente de la misma manera. Coloca tu binario de ClickHouse en una de las rutas de búsqueda predeterminadas (./ci/tmp/clickhouse, ./build/programs/clickhouse, o ./clickhouse); de lo contrario, el job intentará compilar ClickHouse primero:
  python -m ci.praktika run "Fast test"
  

​

Ejecutar pruebas específicas dentro de un job de CI

Con --test, el job prepara la misma configuración de ClickHouse que se usa en CI, pero ejecuta solo las pruebas seleccionadas:

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

• Puedes pasar varios nombres de pruebas:
  python -m ci.praktika run "Stateless tests (amd_debug, parallel)" \
    --test 00001_select1 00002_log_and_exception_messages_formatting
  
• Consejo: Si te sirve cualquier configuración de ClickHouse y solo necesitas ejecutar pruebas específicas, usa el alias functional en lugar del nombre completo del job:
  python -m ci.praktika run functional --test 00001_select1
  

​

Opciones adicionales de personalización

• --path PATH — ruta personalizada al binario de ClickHouse. De forma predeterminada, el ejecutor busca en este orden: ./ci/tmp/clickhouse, ./build/programs/clickhouse, ./clickhouse.
• --count N — repite cada prueba N veces.
• --workers N — reemplaza el cálculo automático del número de workers en paralelo en función de la capacidad de la máquina.

​

Comprobación de compilación

Compila ClickHouse en distintas configuraciones para usarlo en los pasos siguientes.

​

Ejecutar compilaciones en local

La compilación puede ejecutarse localmente en un entorno similar al de CI mediante:

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

No se requieren más dependencias que Python 3 y Docker.

​

Jobs de compilación disponibles

Los nombres de los jobs de compilación son exactamente los que aparecen en el informe de CI:

Compilaciones AMD64:

• Build (amd_debug) - Compilación de depuración con símbolos
• Build (amd_release) - Compilación optimizada de release
• Build (amd_asan) - Compilación con Address Sanitizer
• Build (amd_tsan) - Compilación con Thread Sanitizer
• Build (amd_msan) - Compilación con Memory Sanitizer
• Build (amd_ubsan) - Compilación con Undefined Behavior Sanitizer
• Build (amd_binary) - Compilación rápida de release sin Thin LTO
• Build (amd_compat) - Compilación de compatibilidad para sistemas más antiguos
• Build (amd_musl) - Compilación con musl libc
• Build (amd_darwin) - Compilación para macOS
• Build (amd_freebsd) - Compilación para FreeBSD

Compilaciones ARM64:

• Build (arm_release) - Compilación optimizada de release para ARM64
• Build (arm_asan) - Compilación con Address Sanitizer para ARM64
• Build (arm_coverage) - Compilación para ARM64 con instrumentación de cobertura
• Build (arm_binary) - Compilación rápida de release para ARM64 sin Thin LTO
• Build (arm_darwin) - Compilación para macOS ARM64
• Build (arm_v80compat) - Compilación de compatibilidad para ARMv8.0

Otras arquitecturas:

• Build (ppc64le) - PowerPC de 64 bits Little Endian
• Build (riscv64) - RISC-V de 64 bits
• Build (s390x) - IBM System/390 de 64 bits
• Build (loongarch64) - LoongArch de 64 bits
• Build (wasm64) - WebAssembly de 64 bits, mediante Emscripten. Experimental: compila el binario clickhouse y verifica que clickhouse local ejecute consultas en Node.js ≥ 24 (el módulo también se ejecuta en navegadores, pero CI todavía no lo verifica)

Si el job se completa correctamente, los resultados de la compilación estarán disponibles en el directorio <repo_root>/ci/tmp/build.

Nota: En las compilaciones que no pertenecen a la categoría “Otras arquitecturas” (que usan compilación cruzada), la arquitectura de la máquina local debe coincidir con el tipo de compilación para generar la compilación solicitada por BUILD_JOB_NAME.

​

Ejemplo

Para ejecutar una compilación local en modo depuración:

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

Si el método anterior no le funciona, use las opciones de cmake del registro de compilación y siga el proceso general de compilación.

​

Pruebas funcionales sin estado

Ejecuta pruebas funcionales sin estado para binarios de ClickHouse compilados con varias configuraciones: release, debug, con sanitizadores, etc. Consulta el informe para ver qué pruebas fallan y, a continuación, reproduce el fallo localmente como se describe aquí. Ten en cuenta que debes usar la configuración de compilación correcta para reproducirlo: una prueba puede fallar con AddressSanitizer, pero pasar en Debug. Descarga el binario desde la página de comprobaciones de compilación de CI o compílalo localmente.

En las pull requests, la mayoría de los jobs de sanitizadores cuyo nombre termina en selected tests no ejecutan toda la suite de pruebas. Ejecutan solo las pruebas seleccionadas para el cambio: las pruebas que la pull request añade o modifica, las pruebas que ya fallaron en esta pull request y las pruebas que cubren las líneas modificadas según la base de datos de cobertura. Los jobs de MSan/WasmEdge siguen ejecutando la suite completa porque las pruebas UDF de Wasm existentes no son compatibles con MSan. La suite completa también se ejecuta en las configuraciones de binarios debug y sin instrumentación, las compilaciones con sanitizadores se prueban mediante la prueba de estrés, y la rama master ejecuta la suite completa en todas las configuraciones.

​

Pruebas de integración

Ejecuta las pruebas de integración.

​

Comprobación de validación de correcciones de errores

Comprueba que haya una prueba nueva (funcional o de integración) o alguna prueba modificada que falle con el binario compilado en la rama master. Esta comprobación se activa cuando la pull request tiene la etiqueta “pr-bugfix”.

​

Prueba de estrés

Ejecuta pruebas funcionales sin estado de forma concurrente desde varios clientes para detectar errores de concurrencia. Si falla:

• Primero, corrige todos los demás fallos de las pruebas;
  • Consulta el informe para encontrar los logs del servidor y revísalos para identificar posibles causas del error.

​

Comprobación de compatibilidad

Verifica que el binario clickhouse funcione en distribuciones con versiones antiguas de libc. Si falla, pide ayuda a un mantenedor.

​

AST fuzzer

Ejecuta consultas generadas aleatoriamente para detectar errores del programa. Si falla, pide ayuda a un responsable del proyecto.

​

Pruebas de rendimiento

Mide los cambios en el rendimiento de las consultas. Esta es la comprobación más larga y tarda algo menos de 6 horas en ejecutarse. El informe de pruebas de rendimiento se describe en detalle aquí.

​

Revertir regresiones de CI

Esto no es una comprobación de tu pull request: se ejecuta en master cada hora y puede revertir un pull request que ya se haya fusionado.

El job toma las pruebas fallidas que la base de datos de CI registró para master durante las últimas 24 horas y las agrupa por nombre de prueba, en todas las comprobaciones en las que falló la prueba. Que una misma prueba falle en la compilación de depuración y en la compilación tsan constituye un único fallo, con una sola causa que investigar, y las comprobaciones en las que apareció se incluyen como evidencia en la investigación: un cambio que rompe una prueba normalmente la rompe en varias compilaciones a la vez. Los fallos que no se atribuyen a ninguna prueba, como un fallo de compilación o un job que se quedó sin tiempo, se omiten: «por qué falla esta comprobación» no tiene una única causa que revertir. Las filas que el arnés de pruebas escribe sobre todo el script bajo un nombre similar al de una prueba, como Test script failed o Server died, se rechazan del mismo modo. Una prueba que falló en más de un commit de master se entrega a un agente de IA, al que se proporciona el repositorio con el historial completo de master y acceso de solo lectura a la base de datos de CI, y que responde a una única pregunta: si este fallo fue introducido por un pull request fusionado recientemente y, de ser así, cuál. El agente no tiene credenciales de GitHub ni forma de obtenerlas — se ejecuta como un usuario sin privilegios independiente, con un entorno vacío y los endpoints de credenciales de Cloud bloqueados por el firewall para ese usuario — y trabaja en un clon desechable del repositorio en lugar de en el checkout del propio job, de modo que nada de lo que concluya — ni nada que pudiera dejar atrás — puede llegar a GitHub salvo mediante las comprobaciones siguientes. El umbral cuenta commits en lugar de filas fallidas, por lo que un commit defectuoso que falla en tres compilaciones sigue siendo una única ocurrencia y no se actúa sobre él. También los cuenta por modo de fallo: las salidas registradas se someten a huellas digitales tras normalizar las partes volátiles (direcciones, timestamps, nombres aleatorios de bases de datos), y una prueba cuyo nombre abarca dos causas diferentes — una regresión en un commit y un fallo intermitente no relacionado en otro — no se considera un fallo repetido, por lo que no se investiga nada hasta que una causa se repite por sí sola.

Solo una respuesta inequívoca da lugar a una acción. Cuando el agente informa de una regresión con alta confianza y el pull request identificado supera las comprobaciones de seguridad (se fusionó en master en los últimos tres días, no es una reversión, no se ha revertido ya y la reversión se aplica limpiamente), el job lo revierte, fusiona la reversión de inmediato sin esperar a las comprobaciones y abre un pull request en borrador titulado Reapply "..." que reintroduce el cambio. Un veredicto de regresión debe indicar tanto el pull request como el commit de master en el que se incorporó, y ambos deben coincidir: el job compara el número con el registro de GitHub sobre el commit de fusión que produjo ese pull request y no actúa sobre ninguno si no coinciden. No se revierte nada una vez que el fallo desaparece: un fallo permanece en la ventana de observación durante un día completo después de dejar de producirse, por lo que, justo antes de revertirlo, el job vuelve a consultar la base de datos de CI; si el fallo está ausente de los commits más recientes de master que ejecutaron todas las comprobaciones afectadas, se registra como ya corregido y se deja sin tocar. Se usan los commits más recientes según el historial de la propia rama, no según cuándo se ejecutaron sus comprobaciones — un commit antiguo cuya comprobación empezó tarde no debe interpretarse como evidencia reciente de éxito. Se considera la ausencia en lugar de un resultado satisfactorio, porque la mayor parte de lo que investiga este job no tiene una fila satisfactoria que encontrar: un error lógico o una comprobación bloqueada se registra con el texto del propio fallo, y solo cuando ocurre. Una comprobación cuenta como que ha ejecutado un commit solo cuando una de sus ejecuciones completó las pruebas: una ejecución que se abortó a mitad de camino — registrada por el arnés como Test script failed o Server died junto a las filas de pruebas que sí produjo — ejecutó algunas pruebas, no necesariamente esta, y su silencio sobre el fallo no es evidencia; sí lo es una nueva ejecución de la misma comprobación que se completó en el mismo commit. Cuánta ausencia basta depende de la frecuencia con la que se produce el fallo — un par de commits limpios no significan nada para algo que falla una vez cada cien ejecuciones, por lo que el requisito es superar el período más largo registrado en el que el fallo dejó de producirse entre sus propias ocurrencias. Cuando no se puede responder a la pregunta en absoluto — una comprobación en la que se observó el fallo ya no informa con ese nombre, o el historial de commits desde que comenzó el fallo es más largo de lo que devuelve la consulta — eso también se registra y no se revierte nada. Como máximo se revierten dos pull requests por ejecución.

Si tu pull request fue revertido:

• El pull request de reversión explica qué falla y por qué se atribuyó el fallo al cambio. Si la atribución es incorrecta, indícalo allí y vuelve a incorporar el cambio.
• El pull request en borrador Reapply "..." conserva tu cambio sin modificar. Corrige el fallo en esa rama, márcalo como listo para revisión y deja que pase por la CI normal.

Cada investigación se registra en la tabla checks_investigated de la base de datos de CI, incluidas aquellas que no revierten nada. Los valores se trasladan desde checks tal como se registraron allí, por lo que las dos tablas se pueden volver a unir — directamente por test_name; mediante has(check_names, check_name) y has(commit_shas, commit_sha) para las columnas que agrupan varias filas de checks en un array; y mediante offending_pull_request_number = pull_request_number para el pull request responsable —. El historial de lo que examinó el job, a qué conclusión llegó y qué hizo se puede consultar en 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;

El job está implementado en ci/jobs/revert_ci_regressions.py y se ejecuta como parte del flujo de trabajo Hourly. Al ejecutarlo con --dry-run, inspecciona y evalúa cada salvaguarda, pero no modifica nada: ninguna tabla, ninguna fila, ninguna rama, ningún pull request ni ningún merge; en su lugar, imprime las filas que habría escrito. Un flujo de trabajo independiente, .github/workflows/revert_broken_prs.yml, revierte los merges que se realizaron mientras su propia CI estaba en rojo; ambos usan el mismo nombre de rama revert-<pull request number>, por lo que un pull request nunca se revierte dos veces. Un revert iniciado manualmente también cuenta: el job no actúa si el revert ya está en master, si existe una rama llamada revert-<pull request number> o revert-<pull request number>-<branch> (lo que crea el botón Revert de GitHub), o si hay un pull request abierto o integrado desde una de esas ramas.