A template for AI-driven C/C++ development with a complete CI/CD pipeline: build and test on every major toolchain, lint, sanitize, measure coverage, generate Doxygen documentation, and release to every common C/C++ distribution channel from changelog fragments.
It is the C++ member of the link-foundation template family
(Rust,
Python,
JavaScript,
PHP):
the same job graph, triggers, release model and hardening, following the
CI/CD best practices,
and it covers what the linksplatform C++
libraries need (header-only template libraries, NuGet TemplateLibrary
packages, Conan, GitHub Pages documentation).
- Single-language and multi-language repositories: the C++ project lives at
the repository root (tags
v1.2.3) or undercpp/next torust/,js/,python/... (tagscpp_v1.2.3). Every script detects the layout; see docs/multi-language.md. - Modern CMake: an
INTERFACE(header-only) library target with an alias, install rules, a relocatable CMake package config, a pkg-config file, and CMake presets (cmake --workflow --preset dev). - Every distribution channel, each one exercised by CI on every pull
request (docs/distribution.md):
- the repository itself:
add_subdirectory, git submodule,FetchContent, CPM.cmake; find_packageaftercmake --install, and pkg-config;- GitHub releases: reproducible source archives, the install tree, a vcpkg
overlay port and
SHA256SUMS; - vcpkg (overlay port or registry), Conan 2 (
conanfile.pyandtest_package), and native NuGet packages for Visual Studio.
- the repository itself:
- Cross-platform testing: GCC and Clang on Ubuntu, Apple Clang on macOS, and MSVC on Windows, in Debug and Release, with GoogleTest; benchmarks with Google Benchmark.
- Code quality: clang-format, clang-tidy and cppcheck at pinned versions, warnings as errors, file size limits, and pre-commit hooks.
- Sanitizers and coverage: AddressSanitizer and UndefinedBehaviorSanitizer over the test suite; gcov and gcovr with a line coverage floor, uploaded to Codecov when a token is configured.
- Documentation: Doxygen API reference that fails on undocumented public symbols, published to GitHub Pages (docs/ci-cd.md).
- Release automation: changelog fragments decide the semantic version
bump; the pipeline bumps the version, updates
CHANGELOG.md, tags, and publishes every configured channel, and it heals a release that failed half-way. - Hardened pipeline: least-privilege permissions, hash-pinned third-party actions, credential preflight probes, CodeQL, dependency review, secret scanning, actionlint, zizmor, a broken link checker, a terminal pipeline status gate, and automatic re-runs of jobs GitHub never gave a runner.
-
Click "Use this template" on GitHub to create a new repository, and clone it.
-
Rename the placeholder package
my_packageand the repository URLs:python3 scripts/rename_project.py your_library --repository your-org/your-repo git diff # review, then commit -
Replace the example code in
include/,tests/,examples/andbenchmarks/with your own, and describe the library indocs/mainpage.md. -
Configure the publishing channels you need (see Configuration).
-
Add a changelog fragment to every pull request (see CONTRIBUTING.md).
For a multi-language repository, move the C++ project into cpp/ (see
docs/multi-language.md).
You need CMake 3.25 or newer (CI uses 4.5.0), a C++20 compiler, Python 3.15.2 and git. Ninja is
optional. The tests download GoogleTest with FetchContent unless it is
installed.
# Configure, build and run the tests (Debug)
cmake --workflow --preset dev
# The same in Release, with the benchmarks
cmake --workflow --preset release
# Tests under AddressSanitizer and UndefinedBehaviorSanitizer (GCC/Clang)
cmake --workflow --preset asan
# Build and run the consumer examples (every way to use the library)
python3 scripts/check_consumers.pyThe lint tools are pinned in scripts/requirements-ci.txt, so everyone runs
the versions CI runs:
python3 -m pip install -r scripts/requirements-ci.txt
# clang-format, clang-tidy and cppcheck (needs the compile database)
cmake --preset lint
python3 scripts/lint_cpp.py
# Apply clang-format
clang-format -i include/*/*.hpp tests/*.cpp examples/*.cpp benchmarks/*.cpp
# Coverage report (gcovr.cfg sets the filter and the floor)
cmake --workflow --preset coverage
gcovr --object-directory build/coverage
# Tests of the release scripts
python3 -m pytest scripts/tests
# clang-format, the file size check and the script tests on every commit
pre-commit install.
├── CMakeLists.txt # the library; project(VERSION) is the single version source
├── CMakePresets.json # dev, release, asan, coverage, lint, install presets
├── cmake/ # warnings, sanitizers, dependencies, install and package config
├── include/my_package/ # the public headers
├── tests/ # GoogleTest unit tests
├── benchmarks/ # Google Benchmark benchmarks
├── examples/ # basic_usage.cpp and examples/consumers/*
├── conanfile.py, test_package/ # Conan 2 recipe and its test package
├── vcpkg.json # vcpkg manifest (dependencies of tests and benchmarks)
├── packaging/ # templates of the vcpkg port and the NuGet package
├── Doxyfile, docs/ # Doxygen configuration, main page and documentation
├── changelog.d/ # changelog fragments of unreleased changes
├── scripts/ # CI/CD scripts (Python standard library and bash) and their tests
└── .github/workflows/ # release.yml, docs.yml, security.yml, links.yml, workflows.yml
.github/workflows/release.yml (CI/CD Pipeline) runs on pull requests,
pushes to main and manual dispatch. Pull requests get change detection,
changelog and version checks, a secrets scan, fresh-merge simulation, lint,
the test matrix, sanitizers, coverage, the release script tests and a
packaging dry run of every channel. Pushes to main additionally release when
changelog fragments are pending. docs/ci-cd.md describes
every job, the release flow and the other workflows.
Without publishing configuration the pipeline builds, tests and creates GitHub releases with all the release assets. Native vulnerability auditing requires a provider token; missing configuration is explicitly incomplete on PRs and fails main/scheduled/manual security runs. Set repository variables (Settings → Secrets and variables → Actions → Variables) and secrets to enable more:
| Name | Kind | Purpose |
|---|---|---|
NUGET_MAX_PACKAGE_BYTES |
variable | Compressed NuGet package budget in bytes (default 249000000); enforced on PRs and releases |
NUGET_PUBLISH |
variable | true pushes the NuGet package on release |
NUGET_PACKAGE_ID |
variable | NuGet package id, e.g. Platform.Numbers.TemplateLibrary |
NUGET_USER |
variable | nuget.org profile name for trusted publishing; takes priority over the API key |
NUGET_API_KEY |
secret | fallback nuget.org API key with push scope for that id when NUGET_USER is unset |
CONAN_REMOTE_URL |
variable | Conan remote to upload releases to |
CONAN_LOGIN_USERNAME |
variable or secret | Conan remote user |
CONAN_PASSWORD |
secret | Conan remote password or token |
CONAN_AUDIT_PROVIDER_TOKEN_CONANCENTER |
secret | required for complete native security coverage; provider setup and failure policy |
RELEASE_ARCHIVE_BASENAME |
variable | release archive name, e.g. platform.numbers_{version} |
CODECOV_TOKEN |
secret | uploads coverage to Codecov |
DEPLOY_GITHUB_PAGES |
variable | true deploys the Doxygen reference to GitHub Pages |
MACOS_NON_BLOCKING |
variable | true lets a failing or runner-less macOS test leg stop blocking releases; runner-acquisition failures |
CI_VERBOSE |
variable | true prints every candidate job when re-running jobs that never got a hosted runner |
The Release Preflight job checks credentials alongside the build and
blocks releases on refused credentials. NuGet API keys are checked against
an existing package version; first-push scope and deferred OIDC exchanges
are reported as unknown. To use trusted publishing, register a nuget.org
policy for this repository and release.yml, then set NUGET_USER to your
profile name. See NuGet publishing.
The branch protection of main should require the Pipeline Status check.
The CMake options are prefixed with the package name:
| Option | Default | Purpose |
|---|---|---|
MY_PACKAGE_BUILD_TESTS |
top-level project | Build the unit tests |
MY_PACKAGE_BUILD_EXAMPLES |
top-level project | Build the examples |
MY_PACKAGE_BUILD_BENCHMARKS |
OFF |
Build the benchmarks |
MY_PACKAGE_BUILD_DOCS |
top-level project | Add the my_package_docs Doxygen target |
MY_PACKAGE_INSTALL |
top-level project | Generate the install and package config rules |
MY_PACKAGE_FETCH_DEPENDENCIES |
ON |
Download missing test dependencies |
MY_PACKAGE_WARNINGS_AS_ERRORS |
OFF |
Treat warnings as errors (the presets turn it on) |
MY_PACKAGE_SANITIZERS |
empty | Sanitizers for the tests, e.g. address;undefined |
MY_PACKAGE_ENABLE_COVERAGE |
OFF |
Instrument the tests for coverage |
MY_PACKAGE_NATIVE_ARCH |
OFF |
Tune tests and benchmarks for the host CPU |
A project consumed through add_subdirectory, FetchContent or CPM only
gets the library target: tests, examples, docs and install rules default to
on only when the project is the top-level one.
Contributions are welcome. CONTRIBUTING.md covers the development setup, the pull request process and changelog fragments. In short:
- Create a branch and make your changes, with tests.
- Run
cmake --workflow --preset devand the lint checks. - Add a changelog fragment to
changelog.d/. - Open a pull request; the version is bumped by the release pipeline, never by hand.
Unlicense: public domain.