CI/CD on kenji.blog

Construindo um Pipeline CI/CD para Projetos C++ usando GitHub Actions

Sat, 12 Sep 2026 18:00:00 +0900

Construindo um Pipeline CI/CD para Projetos C++ usando GitHub Actions: O Guia Completo

No paradigma moderno de desenvolvimento de software, a Integração Contínua (Continuous Integration: CI) e a Entrega/Implantação Contínua (Continuous Delivery/Deployment: CD) são elementos indispensáveis para processos de desenvolvimento ágeis e para a manutenção de software de alta qualidade. Com inúmeras linguagens de programação disponíveis, a construção de um pipeline CI/CD em C++ envolve dificuldades e complexidades únicas em comparação com outras linguagens (como Python, JavaScript, Go, etc.).

Neste artigo, explicaremos de forma extremamente detalhada como construir um pipeline CI/CD robusto e prático do zero para um projeto C++ utilizando o GitHub Actions. Cobriremos todas as técnicas práticas, incluindo builds em matriz multiplataforma (Windows, Linux, macOS), integração do sistema de build com CMake, testes automatizados usando CTest, automação de análises estáticas e dinâmicas, medição de cobertura (coverage) e entrega automática de binários compilados através do GitHub Releases.

1. O Significado e os Desafios Únicos do CI/CD em Projetos C++

No desenvolvimento de aplicações web ou uso de linguagens de script, testar e compilar em um único contêiner Docker costuma ser suficiente na maioria dos casos. No entanto, o C++ é uma linguagem compilada nativamente e depende fortemente da arquitetura de hardware e do sistema operacional do ambiente de execução.

Ao introduzir CI/CD em um projeto C++, os principais desafios enfrentados são:

Diversidade de Plataformas: Diferentes SOs como Windows, Linux e macOS têm APIs distintas (Windows API, POSIX, etc.). É muito comum que um código funcione no ambiente local do desenvolvedor (por exemplo, macOS) mas falhe na compilação no Linux ou Windows.
Diferenças entre Compiladores: Compiladores principais como Microsoft Visual C++ (MSVC), GNU Compiler Collection (GCC) e Clang variam no grau de implementação do padrão C++ (C++17, C++20, C++23), em suas interpretações e na severidade dos avisos (warnings).
Tempo de Compilação (Build): Em projetos C++ de grande escala, não é incomum que a compilação demore de dezenas de minutos a várias horas. No ambiente de CI, com recursos computacionais limitados, estratégias de cache e paralelização são necessárias para compilar de forma eficiente.
Gerenciamento de Dependências: Diferente de npm ou pip, o C++ não possui um gerenciador de pacotes padrão absoluto. É necessário resolver bibliotecas corretamente em cada execução no ambiente CI usando ferramentas como vcpkg, Conan ou o FetchContent do CMake.
Gerenciamento de Memória e Comportamento Indefinido (Undefined Behavior): Como envolve manipulação de ponteiros e gerenciamento manual de memória, além de testar a lógica, também é necessário automatizar a detecção de vazamentos de memória (memory leaks) e comportamentos indefinidos.

Para resolver esses desafios, o GitHub Actions se torna a solução ideal, pois permite provisionar várias máquinas virtuais de SO sob demanda e definir fluxos de trabalho complexos via código (Configuration as Code).

2. Visão Geral da Arquitetura do Pipeline CI/CD

Vamos visualizar todo o pipeline CI/CD que construiremos. O diagrama de sequência Mermaid a seguir mostra o fluxo de trabalho desde o push do código até a release.

sequenceDiagram
participant Dev as "Desenvolvedor"
participant Repo as "Repositório GitHub"
participant Action as "GitHub Actions CI/CD"
participant Rel as "GitHub Releases"
Dev->>Repo: "Fazer push da branch / Abrir PR"
Repo->>Action: "Acionar Workflow de CI"
activate Action
Action->>Action: "Lint & Análise Estática (Clang-Tidy)"
rect rgb(200, 220, 240)
note right of Action: "Build em Matriz Multiplataforma"
Action->>Action: "Build no Ubuntu (GCC/Clang)"
Action->>Action: "Build no Windows (MSVC)"
Action->>Action: "Build no macOS (Apple Clang)"
end
Action->>Action: "Executar CTest (com ASAN/UBSAN)"
Action->>Action: "Gerar Relatório de Cobertura"
alt "Se uma Tag sofrer push (ex: v1.0.0)"
Action->>Action: "Empacotar Binários com CPack"
Action->>Rel: "Fazer upload do ZIP/Tarball para a Release"
end
deactivate Action
Repo-->>Dev: "Reportar Status do CI (Passou/Falhou)"

Nessa arquitetura, fornecemos feedback rápido (análise estática, build e testes) na fase de Pull Request, e realizamos o empacotamento e a distribuição dos artefatos no momento em que uma tag de versão é adicionada.

3. Configuração do Projeto com CMake Moderno

A base de um excelente pipeline de CI é um sistema de build robusto. Usaremos o CMake, que é o padrão de fato para C++. Aqui, adotaremos a abordagem orientada a alvos (target-oriented) conhecida como “CMake Moderno”.

Assumimos a seguinte estrutura de diretórios para o projeto:

1
2
3
4
5
6
7
8
9


my_cpp_project/
├── CMakeLists.txt
├── src/
│ ├── main.cpp
│ ├── calculator.cpp
│ └── calculator.h
└── tests/
 ├── CMakeLists.txt
 └── test_calculator.cpp

Exemplo de configuração do CMakeLists.txt na raiz:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47


cmake_minimum_required(VERSION 3.20)
project(MyCppProject VERSION 1.0.0 LANGUAGES CXX)

# Configuração do padrão C++
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF) # Desativa extensões específicas do compilador para aumentar a portabilidade

# Rigor nos avisos do compilador
function(set_project_warnings target_name)
 if(MSVC)
 target_compile_options(${target_name} PRIVATE /W4 /WX)
 else()
 target_compile_options(${target_name} PRIVATE -Wall -Wextra -Wpedantic -Werror)
 endif()
endfunction()

# Criação do alvo da biblioteca
add_library(CalculatorLib src/calculator.cpp)
target_include_directories(CalculatorLib PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/src)
set_project_warnings(CalculatorLib)

# Criação do alvo do executável
add_executable(MyApplication src/main.cpp)
target_link_libraries(MyApplication PRIVATE CalculatorLib)
set_project_warnings(MyApplication)

# Habilitação de testes
enable_testing()
add_subdirectory(tests)

# Definição das regras de instalação (para CPack)
include(GNUInstallDirs)
install(TARGETS MyApplication CalculatorLib
 RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
 LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
 ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
)

# Configurações de empacotamento com CPack
set(CPACK_PROJECT_NAME ${PROJECT_NAME})
set(CPACK_PROJECT_VERSION ${PROJECT_VERSION})
set(CPACK_GENERATOR "ZIP;TGZ")
if(WIN32)
 set(CPACK_GENERATOR "ZIP")
endif()
include(CPack)

Pontos importantes:

CMAKE_CXX_EXTENSIONS OFF: Previne a dependência de recursos não padronizados, como extensões GNU, garantindo a natureza multiplataforma.
Rigor nos avisos (-Werror / /WX): Ao tratar os avisos do compilador como erros no ambiente de CI, mantemos a qualidade do código forçadamente alta.
GNUInstallDirs: Resolve automaticamente os caminhos de instalação padrão específicos do SO (como /usr/local/bin ou C:\Program Files).

4. O Básico do GitHub Actions e a Estratégia de Matriz

O GitHub Actions é configurado através de arquivos YAML dentro do diretório .github/workflows/. O recurso mais poderoso para projetos C++ é a “Estratégia de Matriz” (Matrix Strategy). Isso permite gerar dinamicamente combinações de SOs e compiladores e executá-las em paralelo.

graph TD
A["Acionar Workflow"] --> B["Avaliação de Job em Matriz"]
B --> C["Ubuntu 22.04 (GCC 12)"]
B --> D["Ubuntu 22.04 (Clang 15)"]
B --> E["Windows Server 2022 (MSVC)"]
B --> F["macOS 14 (Apple Clang)"]

Abaixo mostramos a definição de job em YAML, que é a base para o build em matriz.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


jobs:
 build:
 name: "Build & Test [${{ matrix.os }} - ${{ matrix.compiler }}]"
 runs-on: ${{ matrix.os }}
 strategy:
 fail-fast: false # Continua o build de outros SOs mesmo se um job falhar
 matrix:
 include:
 - os: ubuntu-latest
 compiler: gcc
 c_compiler: gcc
 cpp_compiler: g++
 - os: ubuntu-latest
 compiler: clang
 c_compiler: clang
 cpp_compiler: clang++
 - os: windows-latest
 compiler: msvc
 c_compiler: cl
 cpp_compiler: cl
 - os: macos-latest
 compiler: apple-clang
 c_compiler: clang
 cpp_compiler: clang++

fail-fast: false é muito importante. Por exemplo, se usarmos por engano uma API exclusiva do Linux, o build no Ubuntu falhará, mas ainda queremos ver ao mesmo tempo se o build no Windows é bem-sucedido.

5. Otimização do Tempo de Build e da Limitação de Custo com a Lei de Amdahl

CI/CD em ambiente de nuvem é uma batalha contra o tempo, e o tempo de build se traduz diretamente no tempo de espera do desenvolvedor e nos custos de execução. Aqui, abordaremos matematicamente a otimização do tempo de compilação usando a “Lei de Amdahl” (Amdahl’s Law) da ciência da computação.

A Lei de Amdahl define que, quando a proporção da parte paralelizada de um programa é $P$, o ganho máximo teórico de velocidade $S(N)$ ao usar $N$ processadores é:

$$ S(N) = \frac{1}{(1 - P) + \frac{P}{N}} $$

No processo de build do C++, a compilação de cada unidade de tradução (Translation Unit: arquivos .cpp) do código-fonte é totalmente independente e pode ser paralelizada. Por outro lado, a configuração do CMake e a fase de vinculação (linkagem) do binário final geralmente são executadas em série (não podem ser paralelizadas).

Suponha que, de todo o tempo de build do projeto, 80% seja a fase de compilação ($P = 0.8$) e 20% seja a fase serial ($1 - P = 0.2$). Os runners padrão do GitHub Actions (Linux) fornecem 2 núcleos (threads). Portanto, para $N = 2$:

$$ S(2) = \frac{1}{0.2 + \frac{0.8}{2}} = \frac{1}{0.2 + 0.4} = \frac{1}{0.6} \approx 1.67 $$

Usando apenas 2 núcleos, obtemos uma melhoria de velocidade de cerca de 1,67 vezes. Para alcançar isso, é essencial especificar a opção --parallel no comando de build do CMake.

1
2


 - name: "Build Project"
 run: cmake --build build --config Release --parallel 2

Além disso, também consideramos os custos. O custo de utilização do GitHub Actions $C_{total}$ é a soma dos produtos do tempo de execução do job $T_i$ e do preço unitário do runner $R_i$.

$$ C_{total} = \sum_{i=1}^{M} \left( T_i \times R_i \right) $$

Reduzir o tempo de build não apenas acelera o ciclo de feedback, mas também leva diretamente à redução dos custos operacionais do projeto (especialmente para repositórios privados). Se precisar de mais velocidade, é válido adotar o ccache para fazer cache dos resultados de compilação.

6. Testes Automatizados e Integração de Sanitizers

Para evitar bugs precocemente em C++, é altamente recomendado introduzir “sanitizers”, além de testes de unidade, para detectar vazamentos de memória e comportamentos indefinidos durante a execução. Usaremos o AddressSanitizer (ASAN) e o UndefinedBehaviorSanitizer (UBSAN) desenvolvidos pelo Google.

Adicionamos uma opção no CMake para habilitar os sanitizers.

1
2
3
4
5


option(ENABLE_SANITIZERS "Enable ASAN and UBSAN" OFF)
if(ENABLE_SANITIZERS AND CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
 add_compile_options(-fsanitize=address,undefined -fno-omit-frame-pointer)
 add_link_options(-fsanitize=address,undefined)
endif()

Habilitamos essa opção no job do Ubuntu do pipeline de CI e executamos os testes.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


 - name: "Configure CMake"
 env:
 CC: ${{ matrix.c_compiler }}
 CXX: ${{ matrix.cpp_compiler }}
 run: >
 cmake -B build
 -DCMAKE_BUILD_TYPE=Release
 -DENABLE_SANITIZERS=${{ matrix.os == 'ubuntu-latest' && 'ON' || 'OFF' }}

 - name: "Run CTest"
 working-directory: build
 env:
 ASAN_OPTIONS: "detect_leaks=1:symbolize=1"
 UBSAN_OPTIONS: "print_stacktrace=1"
 run: ctest --build-config Release --output-on-failure --parallel 2

O comando ctest é usado para executar os testes. Especificando --output-on-failure, apenas os logs detalhados de testes reprovados serão exibidos na saída do CI, evitando que o log se torne enorme.

7. Medição da Cobertura de Código (Coverage)

Visualizar quanto de código os testes estão cobrindo é importante para a garantia de qualidade. Usando o ambiente Linux (GCC), medimos a cobertura usando gcov e lcov.

Primeiro, configuramos as flags de compilação no CMake para medir a cobertura.

1
2
3
4
5


option(ENABLE_COVERAGE "Enable coverage reporting" OFF)
if(ENABLE_COVERAGE AND CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
 add_compile_options(--coverage -O0 -g)
 add_link_options(--coverage)
endif()

Definimos um job separado no GitHub Actions para medir a cobertura.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


 coverage:
 name: "Test Coverage Analysis"
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4

 - name: "Install lcov"
 run: sudo apt-get update && sudo apt-get install -y lcov

 - name: "Configure CMake for Coverage"
 run: cmake -B build -DCMAKE_BUILD_TYPE=Debug -DENABLE_COVERAGE=ON

 - name: "Build & Test"
 run: |
 cmake --build build --parallel 2
 cd build && ctest --output-on-failure

 - name: "Generate lcov Report"
 working-directory: build
 run: |
 lcov --capture --directory . --output-file coverage.info
 lcov --remove coverage.info '/usr/*' '*_deps/*' '*tests/*' --output-file coverage.info
 
 - name: "Upload Coverage to Codecov"
 uses: codecov/codecov-action@v3
 with:
 files: build/coverage.info

O comando lcov --remove é usado para excluir headers de sistema, bibliotecas de terceiros e o próprio código de teste da medição de cobertura. Isso garante que a cobertura seja unicamente do código-fonte específico do projeto.

8. Entrega Automática de Binários através do GitHub Releases (CD)

Construímos a parte “CD” do CI/CD. Quando os desenvolvedores adicionam e fazem push de uma tag de versão com Git (ex: v1.2.0), os binários executáveis para cada SO são compilados, empacotados em arquivos ZIP ou Tarball e enviados para o GitHub Releases.

Nesta etapa, usaremos o CPack, a ferramenta de empacotamento incluída no CMake.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


 - name: "Package Application (CPack)"
 if: startsWith(github.ref, 'refs/tags/v')
 working-directory: build
 run: cpack -C Release -V

 - name: "Upload Release Assets"
 if: startsWith(github.ref, 'refs/tags/v')
 uses: softprops/action-gh-release@v1
 with:
 files: |
 build/*.tar.gz
 build/*.zip
 build/*.sh
 build/*.exe
 env:
 GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Com essa configuração, ao executar git tag v1.0.0 e git push origin v1.0.0, um arquivo ZIP para usuários do Windows e um Tarball para usuários Linux/macOS serão automaticamente disponibilizados na página de lançamento, sem intervenção manual. Esse recurso é extremamente poderoso na entrega de software aos usuários.

9. Arquivo Workflow YAML Completo

Abaixo apresentamos o código completo de um arquivo .github/workflows/main.yml robusto e prático, integrando todos os elementos discutidos até agora.

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107


name: "C++ CI/CD Pipeline"

on:
 push:
 branches: [ "main", "develop" ]
 tags: [ "v*.*.*" ]
 pull_request:
 branches: [ "main" ]

env:
 BUILD_TYPE: Release

jobs:
 build-and-test:
 name: "Build [${{ matrix.os }} | ${{ matrix.compiler }}]"
 runs-on: ${{ matrix.os }}
 strategy:
 fail-fast: false
 matrix:
 include:
 - os: ubuntu-latest
 compiler: gcc
 c_compiler: gcc
 cpp_compiler: g++
 - os: ubuntu-latest
 compiler: clang
 c_compiler: clang
 cpp_compiler: clang++
 - os: windows-latest
 compiler: msvc
 c_compiler: cl
 cpp_compiler: cl
 - os: macos-latest
 compiler: apple-clang
 c_compiler: clang
 cpp_compiler: clang++

 steps:
 - name: "Checkout Repository"
 uses: actions/checkout@v4

 - name: "Configure CMake"
 env:
 CC: ${{ matrix.c_compiler }}
 CXX: ${{ matrix.cpp_compiler }}
 run: >
 cmake -B build
 -DCMAKE_BUILD_TYPE=${{ env.BUILD_TYPE }}
 -DENABLE_SANITIZERS=${{ matrix.os == 'ubuntu-latest' && 'ON' || 'OFF' }}

 - name: "Build Project"
 run: cmake --build build --config ${{ env.BUILD_TYPE }} --parallel 2

 - name: "Run Unit Tests (CTest)"
 working-directory: build
 env:
 ASAN_OPTIONS: "detect_leaks=1:symbolize=1"
 UBSAN_OPTIONS: "print_stacktrace=1"
 run: ctest --build-config ${{ env.BUILD_TYPE }} --output-on-failure --parallel 2

 - name: "Package with CPack"
 if: startsWith(github.ref, 'refs/tags/v')
 working-directory: build
 run: cpack -C ${{ env.BUILD_TYPE }}

 - name: "Create GitHub Release and Upload Assets"
 if: startsWith(github.ref, 'refs/tags/v')
 uses: softprops/action-gh-release@v1
 with:
 files: |
 build/*.tar.gz
 build/*.zip
 env:
 GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

 coverage:
 name: "Code Coverage Analysis"
 runs-on: ubuntu-latest
 if: github.event_name == 'pull_request' || github.ref == 'refs/heads/main'
 steps:
 - name: "Checkout Repository"
 uses: actions/checkout@v4

 - name: "Install lcov"
 run: sudo apt-get update && sudo apt-get install -y lcov

 - name: "Configure CMake for Coverage"
 run: cmake -B build -DCMAKE_BUILD_TYPE=Debug -DENABLE_COVERAGE=ON

 - name: "Build Project"
 run: cmake --build build --parallel 2

 - name: "Run Tests"
 working-directory: build
 run: ctest --output-on-failure

 - name: "Generate lcov Report"
 working-directory: build
 run: |
 lcov --capture --directory . --output-file coverage.info
 lcov --remove coverage.info '/usr/*' '*_deps/*' '*tests/*' --output-file coverage.info
 
 - name: "Upload Coverage to Codecov"
 uses: codecov/codecov-action@v3
 with:
 files: build/coverage.info
 fail_ci_if_error: false

10. Para um CI/CD ainda mais Avançado (Análise Estática e Formatação)

Embora omitiremos os detalhes aqui, na prática é recomendado incorporar mais ferramentas de garantia de qualidade ao pipeline.

Obrigatoriedade do Clang-Format: Para reduzir a carga de trabalho na revisão de código, integre verificações de estilo de código com clang-format no CI, falhando o pipeline em caso de violação das regras de formatação.
Análise Estática (Clang-Tidy): Para detectar bugs em potencial que avisos de compilador não capturam, além de códigos ineficientes (como cópias desnecessárias), integre o clang-tidy ao CMake e execute-o no CI.
Uso de Cache do vcpkg / Conan: Se o projeto usa várias bibliotecas de terceiros, compilar as dependências exigirá um tempo considerável. Aproveitando actions/cache do GitHub Actions, podemos manter os diretórios instalados do vcpkg ou o cache do Conan, o que reduz drasticamente o tempo de compilação.

Conclusão

Construir um pipeline CI/CD em um projeto C++ pode, à primeira vista, parecer uma barreira difícil devido às dependências de plataforma e à complexidade das ferramentas de build. No entanto, combinando adequadamente o ecossistema do GitHub Actions, CMake moderno e CTest/CPack, você pode obter um fluxo de desenvolvimento incrivelmente poderoso e automatizado.

A verificação multiplataforma por meio da estratégia de matriz, a detecção de erros de execução com sanitizers, a medição de cobertura (coverage) e a implantação automática via GitHub Releases explicados neste artigo são as melhores práticas amplamente adotadas mesmo em projetos open-source de nível comercial.

Os pipelines de CI/CD automatizados minimizam o tempo que os desenvolvedores gastam para “procurar bugs” ou executar trabalhos de “build e releases manuais”, tornando-se a arma definitiva para concentrar o foco no que realmente importa: na criação e na programação. Por favor, traga esses conceitos e os implemente no seu projeto C++, de forma a garantir uma vida de desenvolvimento mais ágil e despreocupada!

Como hospedar um blog Hugo grátis e super rápido no Cloudflare Pages ou GitHub Pages

Sat, 12 Sep 2026 12:00:00 +0900

Ao gerenciar um site ou blog, a velocidade de carregamento (desempenho), os custos operacionais e a segurança são fatores extremamente importantes. No passado, a combinação de um CMS dinâmico (Content Management System) como o WordPress e um servidor de hospedagem era predominante, mas hoje a arquitetura chamada “Jamstack” está atraindo muita atenção. Entre as opções, combinando o “Hugo” - um gerador de sites estáticos (SSG) ultrarrápido escrito em Go - com serviços de hospedagem modernos como o Cloudflare Pages e o GitHub Pages, é possível construir um ambiente de blog totalmente gratuito e incrivelmente rápido.

Neste artigo, explicaremos a fundo, sob uma perspectiva técnica, as etapas específicas para publicar um site estático usando Hugo no Cloudflare Pages ou GitHub Pages, as diferenças na arquitetura de cada plataforma, a construção de CI/CD (Integração Contínua/Implantação Contínua) usando o GitHub Actions, a otimização de DNS, estratégias de cache e até a introdução de análises de acesso que respeitam a privacidade.

1. O Básico sobre Geradores de Sites Estáticos (SSG) e Jamstack

1.1 Por que sites estáticos?

Sistemas de CMS dinâmicos tradicionais (ex: WordPress) enviam consultas a um banco de dados (como MySQL) e geram o HTML dinamicamente no lado do servidor (como PHP) para cada solicitação do usuário. Embora esse método seja altamente flexível, ele possui baixa tolerância a picos repentinos de tráfego (ou seja, quando algo viraliza ou ataques DDoS) e frequentemente exige uma arquitetura de infraestrutura complexa, como colocar servidores de cache (Redis ou Varnish) na frente.

Por outro lado, geradores de sites estáticos (SSG) que adotam a arquitetura Jamstack (JavaScript, APIs e Markup) geram antecipadamente (no momento do build) todos os arquivos HTML, CSS e JavaScript. Para as solicitações do usuário, o servidor web (ou CDN) simplesmente retorna os arquivos estáticos já gerados, o que permite alcançar uma velocidade impressionante e segurança robusta.

1.2 A Vantagem do Hugo

Há várias opções de SSG, como Next.js, Gatsby, Jekyll e Astro, mas a maior característica do Hugo é a sua velocidade de compilação. Beneficiando-se do processamento simultâneo fornecido pela linguagem Go, a compilação é concluída em apenas alguns segundos, mesmo para sites com milhares a dezenas de milhares de páginas. Isso reduz drasticamente o tempo de espera no pipeline de CI/CD e está diretamente ligado à melhoria da experiência do desenvolvedor (DX: Developer Experience).

2. Comparação da Arquitetura dos Serviços de Hospedagem

A próxima questão é onde hospedar os arquivos estáticos gerados pelo Hugo. Opções típicas incluem o Cloudflare Pages, o GitHub Pages e o Netlify, mas a arquitetura de rede por trás de cada um deles difere.

2.1 CDN e Computação de Borda (Edge Computing)

Todas essas plataformas utilizam uma CDN (Content Delivery Network) distribuída globalmente para entregar conteúdo. No entanto, além do simples armazenamento em cache de arquivos estáticos, o fator de diferenciação é se elas podem executar roteamento de solicitações e reescrita de cabeçalhos no PoP (Point of Presence) mais próximo do usuário, usando a “computação de borda”.

graph TD
A["Usuário (Tóquio)"] -->|Baixa Latência| B["Nó de Borda (NRT)"]
C["Usuário (Nova York)"] -->|Baixa Latência| D["Nó de Borda (EWR)"]
E["Usuário (Londres)"] -->|Baixa Latência| F["Nó de Borda (LHR)"]
B --> G["Armazenamento de Origem / Object Store"]
D --> G
F --> G

2.2 GitHub Pages

O GitHub Pages é um serviço que permite publicar arquivos HTML, CSS e JavaScript diretamente de um repositório GitHub. Por trás dele, são utilizadas CDNs como o Fastly, entregando um desempenho adequado. Contudo, possui recursos de infraestrutura pura mais limitados, havendo restrições quanto à personalização de cabeçalhos (ex: configuração de Cache-Control ou cabeçalhos de segurança), além de que as configurações de redirecionamento dependem de atualizações meta do HTML ou de plugins do Jekyll.

2.3 Cloudflare Pages

O Cloudflare Pages é um serviço de hospedagem de sites estáticos construído na maior rede Anycast do mundo (presente em mais de 275 cidades), orgulhosamente fornecida pela Cloudflare. Ele permite ajustes de desempenho esmagadores, como o suporte padrão ao HTTP/3 (QUIC), otimização de imagens e a integração de funções de borda (Cloudflare Workers). Além disso, não há cobrança por largura de banda, o que significa que pode ser operado gratuitamente independentemente de quão repentinamente o tráfego aumentar, sendo esta uma grande vantagem.

2.4 Netlify

O Netlify é um pioneiro no modelo Jamstack, fornecendo uma DX tudo-em-um que integra funcionalidades de formulário, autenticação (Identity), funções serverless (sem servidor), entre outras. Porém, caso a largura de banda ultrapasse a cota gratuita (100 GB por mês), são geradas cobranças baseadas no consumo que podem ser altas, de modo que é necessário ter cuidado com o controle de custos em blogs que utilizam muitas imagens e vídeos.

3. Cálculo Teórico de Desempenho e Latência (Modelo Matemático com LaTeX)

Ao avaliar o desempenho web, a redução da latência (Latency) é o indicador mais importante. Vamos modelar o quanto a latência pode ser reduzida utilizando uma CDN (Borda) em comparação ao acesso direto ao servidor de origem.

Definiremos a probabilidade da requisição do usuário atingir o cache como a “Taxa de Acertos de Cache” (Cache Hit Ratio), denotada por $C$, onde $0 \le C \le 1$. Seja a latência até o servidor de origem $L_{origin}$, e a latência até o nó de borda mais próximo $L_{edge}$.

A nova latência média $L_{new}$ é calculada como o seguinte valor esperado:

$$ L_{new} = C \times L_{edge} + (1 - C) \times (L_{edge} + L_{origin}) $$

Simplificando esta fórmula, temos:

$$ L_{new} = L_{edge} + (1 - C) \times L_{origin} $$

Por exemplo, se um usuário em Tóquio acessar um servidor de origem localizado na costa leste dos Estados Unidos (Nova York), levando em conta a distância física da fibra óptica e o atraso de processamento nos roteadores, $L_{origin}$ será de aproximadamente 200 ms. Por outro lado, utilizando uma CDN como a Cloudflare, é possível conectar-se ao nó de borda de Tóquio, reduzindo $L_{edge}$ para cerca de 10 ms.

Supondo uma taxa de acertos de cache $C = 0.95$ (95%),

$$ L_{new} = 10 + (1 - 0.95) \times 200 = 10 + 0.05 \times 200 = 10 + 10 = 20 \text{ ms} $$

Dessa forma, com a introdução da CDN, torna-se possível reduzir drasticamente (em cerca de 90%) a latência média, de 210 ms para 20 ms.

4. Construção de um Pipeline CI/CD com GitHub Actions

Para automatizar o processo de atualização de um blog Hugo, construiremos um pipeline CI/CD utilizando o GitHub Actions. Com isso, basta escrever artigos em Markdown localmente e dar um git push para que o processo de compilação execute automaticamente e o site seja implantado no Cloudflare Pages ou GitHub Pages.

O diagrama de sequência a seguir mostra todo o fluxo, desde o envio do artigo (Push) até sua entrega aos usuários.

sequenceDiagram
participant U as "Usuário (Autor)"
participant G as "Repositório GitHub"
participant A as "GitHub Actions"
participant C as "Cloudflare Pages"
participant V as "Visitante"
U->>G: "git push origin main"
G->>A: "Acionar Evento Push"
A->>A: "Checkout e Configurar Hugo"
A->>A: "hugo --minify (Build)"
A->>C: "Implantar no Cloudflare Pages (Upload Direto)"
C-->>A: "URL de Implantação (Sucesso)"
V->>C: "Solicitar Página Web"
C-->>V: "Retornar HTML em Cache (Borda)"

4.1 Configuração de Implantação para o Cloudflare Pages (Upload Direto)

O Cloudflare Pages possui dois métodos: vincular um repositório GitHub para que a compilação ocorra na infraestrutura da Cloudflare, ou fazer o “Direct Upload” (Upload Direto) dos arquivos estáticos previamente compilados com o GitHub Actions. Se você deseja controlar a versão do Hugo com mais rigor e vincular o processo a outras tarefas (testes e otimização de imagens), é recomendável o método de compilação no GitHub Actions e Upload Direto.

Abaixo, um exemplo prático do arquivo .github/workflows/deploy.yml para implantação no Cloudflare Pages.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38


name: "Deploy Hugo site to Cloudflare Pages"

on:
 push:
 branches:
 - "main"
 workflow_dispatch:

jobs:
 build-and-deploy:
 runs-on: "ubuntu-latest"
 steps:
 - name: "Checkout repository"
 uses: "actions/checkout@v4"
 with:
 submodules: "recursive"
 fetch-depth: 0

 - name: "Setup Hugo"
 uses: "peaceiris/actions-hugo@v3"
 with:
 hugo-version: "0.125.0"
 extended: true

 - name: "Build Hugo Site"
 run: "hugo --minify --gc"
 env:
 HUGO_ENVIRONMENT: "production"

 - name: "Deploy to Cloudflare Pages"
 uses: "cloudflare/pages-action@v1"
 with:
 apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
 accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
 projectName: "your-project-name"
 directory: "public"
 gitHubToken: ${{ secrets.GITHUB_TOKEN }}
 branch: "main"

Neste pipeline, utilizamos a opção --minify para minificar HTML/CSS/JS e --gc para remover arquivos desnecessários. Esses são os fundamentos da otimização de desempenho.

5. Mergulho Profundo nas Configurações de DNS: Domínios Personalizados e Registros CNAME / ALIAS

Ao utilizar um domínio personalizado (ex: kenji.blog), a configuração adequada do DNS (Domain Name System) é essencial.

5.1 Restrições dos Registros CNAME e Zone Apex

Normalmente, para apontar um subdomínio (ex: www.kenji.blog) para um serviço externo, usa-se um registro CNAME. Contudo, devido à especificação do DNS (RFC 1034), não é possível definir um registro CNAME no domínio raiz (também conhecido como Zone Apex ou naked domain, ex: kenji.blog). Isso ocorre porque o Zone Apex deve, obrigatoriamente, conter um registro SOA (Start of Authority), registros NS (Name Server) ou MX (Mail Exchange), e há uma regra de que o CNAME não pode coexistir com outros registros de recurso.

5.2 A Solução: ALIAS / ANAME / CNAME Flattening

Para resolver esse problema, os provedores de DNS modernos oferecem suas próprias extensões:

Registros ALIAS / ANAME: O servidor DNS realiza dinamicamente a resolução de nomes no lado do servidor e retorna os registros A finais (endereços IP) para o cliente. Serviços como o Amazon Route 53 suportam isso.
CNAME Flattening: Um recurso fornecido pela Cloudflare. Ele atua como se um CNAME fosse configurado para a Zone Apex, mas o servidor DNS autoritativo da Cloudflare retorna de forma transparente para o cliente o conjunto de endereços IP (registros A e AAAA) que foram resolvidos automaticamente.

Ao utilizar o Cloudflare Pages, delegar os servidores de nomes (nameservers) do seu domínio para a Cloudflare e aproveitar este “CNAME Flattening” é a configuração mais perfeita e de maior desempenho.

6. Estratégias de Cache e Controle de Cabeçalhos HTTP

Outro pilar na aceleração de sites estáticos é a “Estratégia de Cache”. Com o Cloudflare Pages, utilizando o arquivo gerado (arquivo _headers), é possível ter um controle preciso dos cabeçalhos HTTP de resposta.

6.1 Cache de Borda (Edge Cache) vs Cache do Navegador (Browser Cache)

O cache é amplamente dividido em dois tipos: o “Edge Cache” mantido pelo lado da CDN e o “Browser Cache” armazenado no navegador do usuário.

Para os arquivos estáticos (como imagens, CSS e JS que contêm hashes no nome do arquivo), o ideal é que eles sejam mantidos no cache do navegador por longos períodos. Por outro lado, para arquivos HTML, a fim de que as atualizações sejam refletidas imediatamente, a prática comum é ter um tempo de cache de navegador muito curto (ou até mesmo desativado), lidando com essas requisições por meio do edge cache.

Exemplo de configuração do arquivo _headers no Cloudflare Pages:

1
2
3
4
5
6
7
8
9


# Arquivos HTML não usarão o cache do navegador e serão validados sempre
/*.html
 Cache-Control: public, max-age=0, must-revalidate

# Arquivos de recursos (CSS/JS/Imagens) ficarão no cache do navegador por 1 ano
/assets/*
 Cache-Control: public, max-age=31536000, immutable
/img/*
 Cache-Control: public, max-age=31536000, immutable

6.2 Fórmula para Cálculo de Redução dos Custos com Largura de Banda

Ao configurar cabeçalhos de cache apropriados, o volume de transferência de dados do servidor (borda) pode ser drasticamente reduzido. O custo mensal com largura de banda $Cost$ pode ser expresso pelo seguinte modelo, dependendo do volume de transferência $B_i$ de cada recurso, da taxa de acertos do cache $C_i$ e do preço unitário da largura de banda $R$:

$$ Cost = \sum_{i=1}^{n} \left( B_i \times (1 - C_i) \times R \right) $$

Como a taxa de transferência de saída da Cloudflare é gratuita ($R = 0$), o custo monetário direto é $0$. Porém, ao utilizar outras infraestruturas simultaneamente como o GitHub Pages, ou usar serviços como o AWS S3 como backend, maximizar essa taxa de acertos de cache $C_i$ se torna o pilar para a redução dos custos da infraestrutura.

7. Análise de Acesso que Equilibra Privacidade e Desempenho

Ao gerir um blog, a análise de acesso (Web Analytics) é essencial para saber quantos usuários o estão visitando. O Google Analytics (GA4) foi o padrão da indústria por muito tempo, mas com a recente tendência voltada para a proteção de privacidade (GDPR, CCPA) e a depreciação dos cookies de terceiros, o cenário está mudando.

7.1 Impacto no Desempenho da Web

A adoção do Google Analytics (especificamente o gtag.js e o Google Tag Manager) resulta no carregamento e execução de inúmeros scripts externos, prejudicando o desempenho (especialmente o tempo de TTFB e o tempo de bloqueio da thread principal).

Vamos tentar dividir e considerar o tempo de carregamento de um site da seguinte maneira:

pie title "Repartição Típica do Tempo de Carregamento do Site"
"TTFB (Time to First Byte)" : 15
"Download de Conteúdo (HTML/CSS)" : 20
"DOM Parsing & Renderização" : 45
"Analytics & JS de Terceiros" : 20

Não é raro que ferramentas analíticas JS de terceiros representem entre cerca de 20% a 30% do tempo total de carregamento.

7.2 Implementando o Cloudflare Web Analytics

Assim, ferramentas de análises de acesso que colocam a privacidade em primeiro lugar e não utilizam cookies (Cookieless), como o Cloudflare Web Analytics e o Plausible Analytics, vêm chamando a atenção.

O Cloudflare Web Analytics funciona apenas com a incorporação de um snippet de JavaScript extremamente leve e, como não emite cookies, evita a necessidade de colocar os incômodos banners de consentimento de cookies (Cookie Consent Banner).

A implementação no Hugo também é muito simples. Basta adicionar o snippet fornecido nos arquivos layouts/partials/head.html ou layouts/partials/analytics.html.

1
2
3
4
5


{{ if eq hugo.Environment "production" }}
<!-- Cloudflare Web Analytics -->
<script defer src='https://static.cloudflareinsights.com/beacon.min.js' data-cf-beacon='{"token": "YOUR_CLOUDFLARE_BEACON_TOKEN"}'></script>
<!-- End Cloudflare Web Analytics -->
{{ end }}

Adicionando o atributo defer, o script é carregado de forma assíncrona sem bloquear a análise (parsing) do HTML e executado após a construção do DOM. Dessa forma, é possível minimizar os impactos na velocidade de renderização inicial (LCP: Largest Contentful Paint e FCP: First Contentful Paint).

8. Conclusão e Melhores Práticas

Na operação de sites estáticos usando o Hugo, a adoção de plataformas de hospedagem modernas como o Cloudflare Pages e o GitHub Pages possui vantagens esmagadoras em termos de relação custo-benefício, velocidade de exibição e segurança.

Compilação Extremamente Rápida: Aproveitar a velocidade do Hugo para minimizar o tempo de execução do pipeline de CI/CD (GitHub Actions).
Distribuição na Borda: Usar a rede de borda da Cloudflare para entregar conteúdo a usuários em todo o mundo com latência de milissegundos.
Configuração Apropriada de DNS: Aproveitar o CNAME Flattening para operar a Zone Apex (seu domínio personalizado) de forma segura e rápida.
Otimização de Estratégias de Cache: Usar o arquivo _headers para separar adequadamente o cache de navegador do cache de borda, dependendo do tipo de recurso.
Analytics Mais Leves: Implementar opções como o Cloudflare Web Analytics, que respeitam a privacidade enquanto não comprometem o desempenho.

Combinando tudo isso, é possível construir de forma gratuita um sistema de blog escalável e robusto, capaz de suportar tráfegos de larga escala (de milhões de pageviews mensais). Se você está considerando iniciar um blog de tecnologia, um site corporativo ou um portfólio, por favor não hesite em testar essa configuração composta por Jamstack, Hugo e Cloudflare Pages.