> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Descripción general del sistema de integración continua de ClickHouse
# Integración continua (CI)
Cuando envías un pull request, el sistema de [integración continua (CI)](/es/resources/develop-contribute/contribute/tests#test-automation) 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](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-status-checks).
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:
```shell theme={null}
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](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/resolving-a-merge-conflict-on-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](https://github.com/ClickHouse/ClickHouse/blob/master/.github/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](/es/resources/changelogs/oss/2026)
## 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](https://github.com/docker-library/official-images/tree/master/test#alternate-config-files) 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](https://github.com/ClickHouse/ClickHouse/tree/master/ci/jobs/scripts/docker_server).
## 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`](https://github.com/ClickHouse/ClickHouse/blob/master/ci/jobs/check_style.py) y puede ejecutarse individualmente con `--test ` (véase más abajo).
##### cpp
Comprobaciones del estilo de C++ basadas en expresiones regulares mediante [`check_cpp.sh`](https://github.com/ClickHouse/ClickHouse/blob/master/ci/jobs/scripts/check_style/check_cpp.sh). Si falla, corrige los problemas de estilo según la [guía de estilo de código](/es/resources/develop-contribute/contribute/style).
##### 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/_*`).
##### enlaces simbólicos
Detecta enlaces simbólicos rotos en el repositorio.
##### varios
Comprobaciones varias del repositorio mediante [`various_checks.sh`](https://github.com/ClickHouse/ClickHouse/blob/master/ci/jobs/scripts/check_style/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:
```sh theme={null}
python -m ci.praktika run "Style check"
```
Para ejecutar una comprobación específica (p. ej., la comprobación *cpp*):
```sh theme={null}
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:
```sh theme={null}
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:
```bash theme={null}
python -m ci.praktika run ""
```
* 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:
```bash theme={null}
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:
```bash theme={null}
python -m ci.praktika run "Stateless tests (amd_debug, parallel)" \
--test 00001_select1
```
* Puedes pasar varios nombres de pruebas:
```bash theme={null}
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:
```bash theme={null}
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:
```bash theme={null}
python -m ci.praktika run ""
```
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 `/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:
```bash theme={null}
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](/es/resources/develop-contribute/build/build).
## Pruebas funcionales sin estado
Ejecuta [pruebas funcionales sin estado](/es/resources/develop-contribute/contribute/tests#functional-tests) 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í](/es/resources/develop-contribute/contribute/tests#functional-tests).
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](/es/get-started/setup/self-managed/advanced) 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](#stress-test), y la rama master ejecuta la suite completa en todas las configuraciones.
## Pruebas de integración
Ejecuta las [pruebas de integración](/es/resources/develop-contribute/contribute/tests#integration-tests).
## 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í](https://github.com/ClickHouse/ClickHouse/blob/master/tests/performance/scripts/README.md#how-to-read-the-report).
## 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](https://play.clickhouse.com/):
```sql theme={null}
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-`, 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-` o `revert--` (lo que crea el botón `Revert` de GitHub), o si hay un pull request abierto o integrado desde una de esas ramas.