can be tested 레이블을 추가하면 진행됩니다.
검사 결과는 GitHub checks documentation에 설명된 대로 GitHub 풀 리퀘스트 페이지에 표시됩니다.
검사가 실패하면 수정이 필요할 수 있습니다.
이 페이지에서는 마주칠 수 있는 검사를 개괄적으로 설명하고, 이를 해결하기 위해 수행할 수 있는 작업을 안내합니다.
검사 실패가 변경 사항과 관련이 없어 보인다면, 일시적인 실패이거나 인프라 문제일 수 있습니다.
풀 리퀘스트에 빈 커밋을 푸시하여 CI 검사를 다시 시작하십시오:
master와 머지
Cannot fetch mergecommit 메시지와 함께 실패합니다.
이 검사를 통과하려면 GitHub 문서에 설명된 대로 충돌을 해결하거나, git을 사용해 master 브랜치를 pull request 브랜치에 머지하십시오.
문서 검사(Mintlify)
pr-autogenerated-docs 레이블이 있어야 합니다.
문서를 변경한 후 검사가 실패하면 보고서를 열어 ERROR 및 WARNING 메시지를 확인하십시오.
설명 검사
Docker 이미지
공식 Docker 라이브러리 테스트
clickhouse/clickhouse-server Docker 이미지가 올바르게 동작하는지 확인합니다.
새 테스트를 추가하려면 디렉터리 ci/jobs/scripts/docker_server/tests/$test_name를 만들고 그 안에 run.sh 스크립트를 생성하십시오.
테스트에 대한 추가 정보는 CI jobs scripts 문서에서 확인할 수 있습니다.
Marker 검사
Style Check
ci/jobs/check_style.py의 testname에 해당하며, --test <name> 옵션으로 개별 실행할 수 있습니다(아래 참조).
cpp
check_cpp.sh를 통해 정규식 기반 C++ 스타일 검사를 수행합니다. 검사에 실패하면 코드 스타일 가이드에 따라 문제를 수정하세요.
whitespace_check
catch_all
main, 퍼저 진입 지점을 제외한 곳에서는 catch (...)를 금지합니다.
yamllint
.yamllint를 사용해 .github/ 아래의 YAML 워크플로 파일을 린트합니다.
xmllint
tests/ 및 programs/ 디렉터리 아래의 XML 파일을 검증합니다.
functional_tests_check
event_date로 필터링하는 쿼리는 today() 대신 >= yesterday()를 사용해야 하며(자정 무렵의 불안정한 동작을 방지하기 위해), 테스트 파일 이름에는 fail이 포함되면 안 됩니다.
test_numbers_check
tests/queries/0_stateless/<NNNNN>_*)에서 큰 번호 간격을 표시합니다.
심볼릭 링크
기타
various_checks.sh를 통한 기타 리포지토리 검사: system.query_log / system.parts / 기타에 대한 쿼리는 반드시 currentDatabase로 필터링해야 하며, Replicated*MergeTree ZooKeeper 경로에는 테스트별 접두사가 포함되어야 하고, 통합 테스트 디렉터리에는 __init__.py가 있어야 하며, UTF BOM이 없어야 하고, 소스/데이터 파일에는 실행 비트가 설정되어 있지 않아야 하며, 서드파티 docker-compose 이미지에는 :latest 태그를 사용해서는 안 되는 등 다양한 항목을 검사합니다.
로컬에서 Style Check 작업 실행하기
clickhouse/style-test Docker 이미지를 가져와 컨테이너화된 환경에서 작업을 실행합니다.
Python 3와 Docker 외에는 별도의 종속성이 필요하지 않습니다.
stateless tests 실행하기
사전 요구 사항
- Python 3 (표준 라이브러리만)
- Docker
CI 작업을 로컬에서 실행하기
job 이름을 선택한 다음 로컬에서 실행하십시오:
- 항상 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를 빌드하려고 시도합니다:
CI 작업 내에서 특정 테스트 실행
--test를 사용하면 CI에서 사용하는 것과 동일한 ClickHouse 구성을 준비한 뒤, 선택한 테스트만 실행합니다:
- 여러 테스트 이름을 지정할 수 있습니다:
- 팁: ClickHouse 구성은 아무 것이나 상관없고 특정 테스트만 실행하면 되는 경우, 전체 작업 이름 대신 별칭
functional을 사용하세요:
추가 사용자 설정 옵션
--path PATH— ClickHouse 실행 파일의 사용자 지정 경로입니다. 기본적으로 러너는./ci/tmp/clickhouse,./build/programs/clickhouse,./clickhouse순서대로 검색합니다.--count N— 각 테스트를 N번 반복합니다.--workers N— 머신 용량을 기준으로 자동 계산되는 병렬 워커 수를 재정의합니다.
빌드 검사
로컬에서 빌드 실행하기
사용 가능한 빌드 작업
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 빌드
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비트 리틀 엔디안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에서 요청한 빌드를 생성하려면 로컬 머신의 아키텍처가 빌드 유형과 일치해야 합니다.
예시
상태 비저장 기능 테스트
selected tests로 끝나는 대부분의 새니타이저 작업은 전체 테스트 모음을 실행하지 않습니다.
변경 사항에 맞춰 선택된 테스트, 즉 풀 리퀘스트에서 추가하거나 수정한 테스트, 이 풀 리퀘스트에서 이미 실패한 테스트, 그리고 커버리지 데이터베이스에 따라 변경된 줄을 검사하는 테스트만 실행합니다.
기존 Wasm UDF 테스트가 MSan과 호환되지 않으므로 MSan/WasmEdge 작업은 계속 전체 테스트 모음을 실행합니다. Debug 및 일반 바이너리 구성에서도 전체 테스트 모음을 실행하며, 새니타이저가 포함된 빌드는 스트레스 테스트에서 테스트하고, master 브랜치에서는 모든 구성으로 전체 테스트 모음을 실행합니다.
통합 테스트
버그 수정 검증 검사
스트레스 테스트
- 먼저 다른 테스트 실패를 모두 해결하십시오;
- 보고서에서 서버 로그를 찾아 오류의 가능한 원인을 확인하십시오.
호환성 검사
clickhouse 실행 파일이 실행되는지 확인합니다.
실패하면 메인테이너에게 도움을 요청하십시오.
AST fuzzer
성능 테스트
CI 회귀 되돌리기
master에서 실행되며, 이미 머지된 풀 리퀘스트를 되돌릴 수 있습니다.
이 작업은 지난 24시간 동안 CI 데이터베이스가 master에서 기록한 실패 테스트를 가져와, 테스트가 실패한 모든 검사를 기준으로 테스트 이름별로 그룹화합니다.
같은 테스트가 debug 및 tsan 빌드에서 실패했다면 원인을 찾아야 할 단일 실패로 간주하며, 실패가 나타난 검사는 증거로 조사에 포함됩니다. 테스트를 중단시키는 변경은 대개 여러 빌드에서 동시에 문제를 일으킵니다.
빌드 실패나 시간 초과된 작업처럼 특정 테스트에 귀속할 수 없는 실패는 제외합니다. 「이 검사는 왜 실패하는가」라는 질문에는 되돌릴 수 있는 단일한 답이 없기 때문입니다.
Test script failed 또는 Server died처럼 테스트와 유사한 이름으로 테스트 하니스가 전체 스크립트에 대해 기록한 행도 같은 방식으로 제외합니다.
둘 이상의 master 커밋에서 실패한 테스트는 AI 에이전트에 전달됩니다. 이 에이전트에는 전체 master 이력이 있는 리포지토리와 CI 데이터베이스에 대한 읽기 전용 접근 권한이 주어지며, 이 실패가 최근 머지된 풀 리퀘스트로 인해 도입되었는지, 그렇다면 어느 풀 리퀘스트인지라는 단 하나의 질문에 답합니다.
에이전트에는 GitHub 자격 증명도 이를 발급할 방법도 없습니다. 비어 있는 환경에서 독립된 권한 없는 사용자로 실행되며, 해당 사용자의 cloud 자격 증명 엔드포인트는 firewall로 차단됩니다. 또한 작업 자체의 checkout이 아닌 일회용 리포지토리 clone에서 작업하므로, 에이전트의 결론이나 남길 수 있는 어떤 것도 아래 검사 외에는 GitHub에 도달할 수 없습니다.
임계값은 실패 행이 아니라 커밋 수를 계산하므로, 3개의 빌드에서 실패하는 하나의 문제 있는 커밋도 단일 발생으로 간주되어 조치하지 않습니다.
또한 실패 모드별로 계산합니다. 기록된 출력은 변동하는 부분(주소, 타임스탬프, 무작위 데이터베이스 이름)을 정규화하여 지문을 생성합니다. 한 커밋에서는 회귀가 발생하고 다른 커밋에서는 관련 없는 간헐적 실패가 발생하는 등 테스트 이름이 서로 다른 두 원인에 걸친 경우 반복 실패로 간주하지 않으므로, 하나의 원인이 자체적으로 반복될 때까지 조사하지 않습니다.
명확한 답이 있는 경우에만 조치합니다.
에이전트가 높은 신뢰도로 회귀를 보고하고, 지정된 풀 리퀘스트가 안전성 검사를 통과하면(master에 최근 3일 이내 머지됨, 되돌리기 자체가 아님, 아직 되돌려지지 않음, 되돌리기를 충돌 없이 적용할 수 있음), 작업은 이를 되돌리고 검사를 기다리지 않고 즉시 되돌리기를 머지하며 변경을 다시 도입하는 Reapply "..."라는 제목의 초안 풀 리퀘스트를 엽니다.
회귀 판정은 풀 리퀘스트와 해당 변경이 들어온 master 커밋을 모두 지정해야 하며, 둘은 일치해야 합니다. 작업은 해당 번호를 그 풀 리퀘스트가 생성한 머지 커밋에 대한 GitHub 기록과 대조하며, 일치하지 않으면 어느 쪽에도 조치하지 않습니다.
실패가 사라진 후에는 아무것도 되돌리지 않습니다. 실패는 중단된 후에도 하루 동안 관찰 기간에 남아 있으므로, 되돌리기 직전에 작업이 CI 데이터베이스에 다시 질의합니다. 영향을 받은 모든 검사가 실행된 최신 master 커밋에 실패가 없으면 이미 수정된 것으로 기록하고 그대로 둡니다.
검사가 실행된 시점이 아니라 브랜치 자체 이력 기준의 최신 커밋을 사용합니다. 검사가 늦게 시작된 오래된 커밋을 최근의 정상 증거로 해석해서는 안 됩니다.
통과가 아니라 부재를 확인하는 이유는 이 작업이 조사하는 대부분의 항목에는 찾을 수 있는 통과 행이 없기 때문입니다. 논리 오류나 멈춘 검사는 실패 자체의 텍스트로 기록되며, 발생할 때만 기록됩니다.
검사는 해당 실행이 테스트를 끝까지 완료한 경우에만 해당 커밋을 실행한 것으로 간주합니다. 중간에 중단된 실행은 생성한 테스트 행 옆에 하니스가 Test script failed 또는 Server died로 기록하며, 일부 테스트만 실행했을 뿐 반드시 이 테스트를 실행한 것은 아닙니다. 따라서 실패에 대한 기록이 없더라도 증거가 아니지만, 동일한 커밋에서 완료된 동일 검사 재실행은 증거가 됩니다.
필요한 부재의 정도는 실패 발생 빈도에 따라 다릅니다. 100회 중 한 번 실패하는 항목에서는 정상 커밋 몇 개가 아무 의미가 없으므로, 자체 발생 사이에 실패가 나타나지 않았던 기록상 최장 기간보다 더 길어야 합니다.
질문에 전혀 답할 수 없는 경우, 즉 실패가 관찰된 검사가 더 이상 해당 이름으로 보고하지 않거나 실패 시작 이후의 커밋 이력이 쿼리가 반환하는 범위보다 긴 경우도 기록하며 아무것도 되돌리지 않습니다.
실행당 최대 2개의 풀 리퀘스트만 되돌립니다.
풀 리퀘스트가 되돌려진 경우:
- 되돌리기 풀 리퀘스트에는 무엇이 실패했으며 왜 변경이 원인으로 지목되었는지가 설명되어 있습니다. 원인 귀속이 잘못되었다면 그곳에 알리고 변경을 다시 적용하십시오.
Reapply "..."초안 풀 리퀘스트에는 변경 사항이 수정되지 않은 채로 유지됩니다. 해당 브랜치에서 실패를 수정하고, 검토 준비 상태로 표시한 후 일반 CI를 통과하도록 하십시오.
checks_investigated 테이블에 기록됩니다.
값은 checks에 기록된 그대로 유지되므로 두 테이블을 다시 조인할 수 있습니다. 즉, test_name으로 직접 조인하고, 여러 checks 행을 배열로 수집하는 컬럼은 has(check_names, check_name) 및 has(commit_shas, commit_sha)로 조인하며, 원인으로 지목된 풀 리퀘스트는 offending_pull_request_number = pull_request_number로 조인합니다. 작업이 검토한 내용과 내린 결론, 수행한 작업의 이력은 play.clickhouse.com에서 쿼리할 수 있습니다.
ci/jobs/revert_ci_regressions.py에 구현되어 있으며 Hourly 워크플로의 일부로 실행됩니다.
--dry-run으로 실행하면 모든 조건을 확인하고 평가하지만 아무것도 변경하지 않습니다. table, 행, 브랜치, 풀 리퀘스트, 머지가 생성되지 않으며, 대신 기록될 행이 출력됩니다.
별도의 워크플로인 .github/workflows/revert_broken_prs.yml은 자체 CI가 실패한 상태에서 반영된 머지를 되돌립니다. 두 워크플로는 동일한 revert-<pull request number> 브랜치 이름을 사용하므로 풀 리퀘스트가 두 번 되돌려지지 않습니다.
수동으로 시작한 되돌리기도 고려됩니다. 되돌리기가 이미 master에 있거나, revert-<pull request number> 또는 revert-<pull request number>-<branch>라는 브랜치(GitHub의 Revert 버튼이 생성하는 브랜치)가 존재하거나, 이러한 브랜치에서 생성된 풀 리퀘스트가 열려 있거나 머지된 경우 작업은 작업을 수행하지 않습니다.