> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Visão geral do sistema de integração contínua do ClickHouse

# Integração Contínua (CI)

Quando você envia um pull request, algumas verificações automatizadas são executadas no seu código pelo [sistema de integração contínua (CI)](/pt-BR/resources/develop-contribute/contribute/tests#test-automation) do ClickHouse.
Isso acontece depois que um mantenedor do repositório (alguém da equipe do ClickHouse) analisa seu código e adiciona o rótulo `can be tested` ao seu pull request.
Os resultados das verificações são exibidos na página do pull request no GitHub, como descrito na [documentação sobre verificações do GitHub](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-status-checks).
Se uma verificação falhar, talvez seja necessário corrigi-la.
Esta página apresenta uma visão geral das verificações que você pode encontrar e do que pode fazer para corrigi-las.

Se parecer que a falha na verificação não está relacionada às suas alterações, pode ser uma falha transitória ou um problema de infraestrutura.
Envie um commit vazio para o pull request para reiniciar as verificações de CI:

```shell theme={null}
git commit --allow-empty
git push
```

Se não souber o que fazer, peça ajuda a um mantenedor.

<div id="merge-with-master">
  ## Mesclar com master
</div>

Verifica se o PR pode ser mesclado na branch `master`.
Caso contrário, a verificação falhará com a mensagem `Cannot fetch mergecommit`.
Para corrigir essa verificação, resolva o conflito conforme descrito na [documentação do GitHub](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/resolving-a-merge-conflict-on-github) ou faça o merge da branch `master` na branch do seu pull request usando git.

<div id="docs-check">
  ## Verificação da documentação
</div>

Tenta compilar o site de documentação do ClickHouse.
Ela pode falhar se você tiver alterado algo na documentação.
O motivo mais provável é que algum link interno na documentação esteja incorreto.
Acesse o relatório da verificação e procure as mensagens `ERROR` e `WARNING`.

<div id="description-check">
  ## Verificação da descrição
</div>

Verifique se a descrição do seu pull request está em conformidade com o modelo [PULL\_REQUEST\_TEMPLATE.md](https://github.com/ClickHouse/ClickHouse/blob/master/.github/PULL_REQUEST_TEMPLATE.md).
Você precisa especificar uma categoria de changelog para a sua alteração (por exemplo, correção de bug) e escrever uma mensagem compreensível para o usuário descrevendo a alteração em [CHANGELOG.md](/pt-BR/resources/changelogs/oss/2026)

<div id="docker-image">
  ## Imagem Docker
</div>

Compila as imagens Docker do servidor ClickHouse e do Keeper para verificar se foram compiladas corretamente.

<div id="official-docker-library-tests">
  ### Testes oficiais da biblioteca do Docker
</div>

Executa os testes da [biblioteca oficial do Docker](https://github.com/docker-library/official-images/tree/master/test#alternate-config-files) para verificar se a imagem Docker `clickhouse/clickhouse-server` funciona corretamente.

Para adicionar novos testes, crie um diretório `ci/jobs/scripts/docker_server/tests/$test_name` e o script `run.sh` nele.

Mais detalhes sobre os testes podem ser encontrados na [documentação dos scripts de jobs de CI](https://github.com/ClickHouse/ClickHouse/tree/master/ci/jobs/scripts/docker_server).

<div id="marker-check">
  ## Verificação de marcador
</div>

Esta verificação indica que o sistema de CI começou a processar o pull request.
Quando ela está com status 'pending', isso significa que ainda nem todas as verificações foram iniciadas.
Depois que todas as verificações forem iniciadas, o status muda para 'success'.

<div id="style-check">
  ## Style verificação
</div>

Executa várias verificações de estilo na base de código.

Verificações básicas no job Style Verificação:

<div id="cpp">
  ##### cpp
</div>

Executa verificações simples de estilo de código com base em regex usando o script [`ci/jobs/scripts/check_style/check_cpp.sh`](https://github.com/ClickHouse/ClickHouse/blob/master/ci/jobs/scripts/check_style/check_cpp.sh) (que também pode ser executado localmente).
Se falhar, corrija os problemas de estilo de acordo com o [guia de estilo de código](/pt-BR/resources/develop-contribute/contribute/style).

<div id="codespell">
  ##### codespell, aspell
</div>

Verifique se há erros de gramática e de digitação.

<div id="mypy">
  ##### mypy
</div>

Realiza a verificação estática de tipos em código Python.

<div id="running-style-check-locally">
  ### Executando localmente o job *Style Verificação*
</div>

Todo o job *Style Verificação* pode ser executado localmente em um contêiner Docker com:

```sh theme={null}
python -m ci.praktika run "Style check"
```

Para executar uma verificação específica (por exemplo, a verificação de *cpp*):

```sh theme={null}
python -m ci.praktika run "Style check" --test cpp
```

Esses comandos baixam a imagem Docker `clickhouse/style-test` e executam o job em um ambiente em contêiner.
Não são necessárias dependências além de Python 3 e Docker.

<div id="running-stateless-tests">
  ## Executando testes sem estado
</div>

Uma instalação local do ClickHouse com as configurações padrão pode funcionar para casos de teste específicos, mas não consegue executar corretamente todas as consultas de teste. Na CI, cada job instala uma configuração específica do ClickHouse (por exemplo, armazenamento S3, réplicas paralelas), o que pode ser trabalhoso reproduzir manualmente. Para evitar isso, você pode reproduzir localmente qualquer job da CI usando a mesma orquestração da CI — sem precisar de configuração manual.

<div id="ci-prerequisites">
  #### Pré-requisitos
</div>

* Python 3 (apenas a biblioteca padrão)
* Docker

Instale o Docker no Ubuntu, se necessário, e faça login novamente:

```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
```

<div id="run-ci-job-locally">
  #### Execute um job de CI localmente
</div>

Escolha o nome de qualquer job em um relatório de CI e execute-o localmente:

```bash theme={null}
python -m ci.praktika run "<JOB_NAME>"
```

* Sempre coloque o nome do job entre aspas exatamente como ele aparece no relatório de CI (ele pode conter espaços e vírgulas), por exemplo: `"Stateless tests (amd_debug, parallel)"`. Isso define a mesma configuração do ClickHouse e executa os mesmos testes da CI.
* A arquitetura e o tipo de build no nome do job (por exemplo, `amd_debug`) são rótulos específicos da CI. Ao executar localmente, eles não têm efeito — o job usará o binário que você fornecer, na arquitetura em que estiver rodando. O nome do job determina apenas a configuração do ClickHouse e o conjunto de testes (a menos que isso seja sobrescrito com `--test`).
* Na CI, os testes funcionais são divididos em lotes para melhor aproveitamento de recursos. Por exemplo, `"Stateless tests (amd_debug, parallel)"` e `"Stateless tests (amd_debug, sequential)"` juntos cobrem todo o escopo: os testes seguros para paralelismo são executados de forma concorrente, e o restante é executado de forma sequencial. Essa divisão reduz o tempo total da CI ao maximizar o paralelismo sempre que possível. Para reproduzir localmente todo o escopo de testes, execute ambos os lotes.
* Também existe um job de CI, `"Fast test"`, que executa um escopo limitado de testes funcionais para verificar a funcionalidade básica do ClickHouse — ele usa uma build sem todos os módulos opcionais e é a forma mais rápida de detectar regressões. Você pode executá-lo localmente da mesma forma. Coloque o binário do ClickHouse em um dos caminhos de busca padrão (`./ci/tmp/clickhouse`, `./build/programs/clickhouse` ou `./clickhouse`) — caso contrário, o job tentará compilar o ClickHouse primeiro:
  ```bash theme={null}
  python -m ci.praktika run "Fast test"
  ```

<div id="run-specific-tests-within-ci-job">
  #### Executar testes específicos em um job de CI
</div>

Com `--test`, o job prepara um ambiente do ClickHouse idêntico ao usado na CI, mas executa apenas os testes selecionados:

```bash theme={null}
python -m ci.praktika run "Stateless tests (amd_debug, parallel)" \
  --test 00001_select1
```

* Você pode informar vários nomes de teste:
  ```bash theme={null}
  python -m ci.praktika run "Stateless tests (amd_debug, parallel)" \
    --test 00001_select1 00002_log_and_exception_messages_formatting
  ```
* Dica: Se qualquer configuração do ClickHouse servir e você só precisar executar testes específicos, use o alias `functional` em vez do nome completo do job:
  ```bash theme={null}
  python -m ci.praktika run functional --test 00001_select1
  ```

<div id="additional-customization-options">
  #### Opções adicionais de personalização
</div>

* `--path PATH` — caminho personalizado para o binário do ClickHouse. Por padrão, o runner procura nesta ordem: `./ci/tmp/clickhouse`, `./build/programs/clickhouse`, `./clickhouse`.
* `--count N` — repete cada teste N vezes.
* `--workers N` — substitui o cálculo automático do número de workers paralelos com base na capacidade da máquina.

<div id="build-check">
  ## Verificação de build
</div>

Compila o ClickHouse em diferentes configurações para uso nas etapas seguintes.

<div id="running-builds-locally">
  ### Executando builds localmente
</div>

A build pode ser executada localmente em um ambiente semelhante ao de CI com:

```bash theme={null}
python -m ci.praktika run "<BUILD_JOB_NAME>"
```

Nenhuma dependência além de Python 3 e Docker é necessária.

<div id="available-build-jobs">
  #### Jobs de compilação disponíveis
</div>

Os nomes dos jobs de compilação são exatamente os mesmos exibidos no relatório de CI:

**Builds AMD64:**

* `Build (amd_debug)` - Build de depuração com símbolos
* `Build (amd_release)` - Build de release otimizada
* `Build (amd_asan)` - Build com Address Sanitizer
* `Build (amd_tsan)` - Build com Thread Sanitizer
* `Build (amd_msan)` - Build com Memory Sanitizer
* `Build (amd_ubsan)` - Build com Undefined Behavior Sanitizer
* `Build (amd_binary)` - Build de release rápida sem Thin LTO
* `Build (amd_compat)` - Build de compatibilidade para sistemas mais antigos
* `Build (amd_musl)` - Build com musl libc
* `Build (amd_darwin)` - Build para macOS
* `Build (amd_freebsd)` - Build para FreeBSD

**Builds ARM64:**

* `Build (arm_release)` - Build de release otimizada para ARM64
* `Build (arm_asan)` - Build ARM64 com Address Sanitizer
* `Build (arm_coverage)` - Build ARM64 com instrumentação de cobertura
* `Build (arm_binary)` - Build de release rápida para ARM64 sem Thin LTO
* `Build (arm_darwin)` - Build ARM64 para macOS
* `Build (arm_v80compat)` - Build de compatibilidade para ARMv8.0

**Outras arquiteturas:**

* `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

Se o job for concluído com sucesso, os resultados da compilação estarão disponíveis no diretório `<repo_root>/ci/tmp/build`.

**Observação:** Para builds que não estejam na categoria "Outras arquiteturas" (que usam compilação cruzada), a arquitetura da sua máquina local deve corresponder ao tipo de build para gerar a compilação solicitada por `BUILD_JOB_NAME`.

<div id="example-run-local">
  #### Exemplo
</div>

Para executar uma build local de depuração:

```bash theme={null}
python -m ci.praktika run "Build (amd_debug)"
```

Se a abordagem acima não funcionar para você, use as opções do cmake presentes no log de compilação e siga o [processo geral de compilação](/pt-BR/resources/develop-contribute/build/build).

<div id="functional-stateless-tests">
  ## Testes funcionais sem estado
</div>

Executa [testes funcionais sem estado](/pt-BR/resources/develop-contribute/contribute/tests#functional-tests) para binários do ClickHouse compilados em várias configurações -- release, debug, com sanitizers etc.
Consulte o relatório para ver quais testes falham e, em seguida, reproduza a falha localmente, conforme descrito [aqui](/pt-BR/resources/develop-contribute/contribute/tests#functional-tests).
Observe que é preciso usar a configuração de build correta para reproduzir -- um teste pode falhar com o AddressSanitizer, mas passar em Debug.
Baixe o binário na [página de verificações de build do CI](/pt-BR/get-started/setup/self-managed/advanced) ou compile-o localmente.

<div id="integration-tests">
  ## Testes de integração
</div>

Executa os [testes de integração](/pt-BR/resources/develop-contribute/contribute/tests#integration-tests).

<div id="bugfix-validate-check">
  ## Verificação de validação de correção de bug
</div>

Verifica se há um novo teste (funcional ou de integração) ou testes alterados que falham com o binário compilado na branch master.
Esta verificação é acionada quando o pull request tem o rótulo "pr-bugfix".

<div id="stress-test">
  ## Teste de estresse
</div>

Executa testes funcionais sem estado em paralelo a partir de vários clientes para detectar erros relacionados à concorrência. Se falhar:

* Corrija primeiro todas as outras falhas de teste;
  * Consulte o relatório para localizar os logs do servidor e verifique-os em busca de possíveis causas
    do erro.

<div id="compatibility-check">
  ## Verificação de compatibilidade
</div>

Verifica se o binário `clickhouse` roda em distribuições com versões antigas da libc.
Se falhar, peça ajuda a um mantenedor.

<div id="ast-fuzzer">
  ## AST fuzzer
</div>

Executa consultas geradas aleatoriamente para identificar erros no programa.
Se falhar, peça ajuda a um mantenedor.

<div id="performance-tests">
  ## Testes de desempenho
</div>

Meça as mudanças no desempenho das consultas.
Esta é a verificação mais demorada e leva pouco menos de 6 horas para ser executada.
O relatório do teste de desempenho é descrito em detalhes [aqui](https://github.com/ClickHouse/ClickHouse/blob/master/tests/performance/scripts/README.md#how-to-read-the-report).