How to Set Up CI for C++ (CMake) With GitHub Actions

Configure and build with cmake, run the suite with ctest, and cache the build directory to speed reconfigures.

Configure the build with cmake -B build, compile with cmake --build, and run tests with ctest. An OS matrix exercises the toolchains you ship on, and caching the build dir speeds incremental work.

Steps

• Check out the code.
• Cache the build/ directory keyed on the CMake files.
• Configure with cmake -B build -DCMAKE_BUILD_TYPE=Release.
• Build with cmake --build build and test with ctest.

Workflow

name: CI
on:
  push:
    branches: [main]
  pull_request:
jobs:
  build:
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/cache@v4
        with:
          path: build
          key: cmake-${{ matrix.os }}-${{ hashFiles('**/CMakeLists.txt') }}
      - run: cmake -B build -DCMAKE_BUILD_TYPE=Release
      - run: cmake --build build --config Release
      - run: ctest --test-dir build --output-on-failure

Gotchas

• ctest only sees tests registered via add_test or gtest_discover_tests in CMake.
• On Windows runners, pass --config Release to both build and ctest for multi-config generators.

Related guides