Skip to content

Check your game in CI

Your project’s ctest is worth most when it runs on every push. This workflow builds the project from Start your own project on a GitHub-hosted Windows runner and runs its tests, the rules test and the start-up check from Test your game. Save it in your repository as .github/workflows/ci.yml. A starter project has it there already; it runs once the project is a Git repository on GitHub, whether the engine is in it as the plain files the ZIP gave or as a submodule. Put your project on GitHub takes a starter project there step by step, from making the account to reading the first run:

.github/workflows/ci.yml
# Builds the game and runs its tests on every push and pull request, on a
# GitHub-hosted Windows runner. It goes in .github/workflows/ci.yml.
#
# An example to copy and own, not an action anybody maintains: when the
# project grows a preset, a dependency or a second platform, this file grows
# with it.
name: build and test
on:
push:
pull_request:
workflow_dispatch:
jobs:
windows:
runs-on: windows-latest
# Well above a build with nothing cached, so a stalled step fails the run
# rather than holding it for GitHub's six-hour default.
timeout-minutes: 90
# The presets use the Ninja generator, so every cmake step runs in a
# Command Prompt with the MSVC environment, as on your machine.
defaults:
run:
shell: cmd
steps:
# If the engine is a submodule, a checkout without this has an empty
# external/labrador, and a private submodule needs a token as well. With
# the engine as plain files, as a starter project is committed, it does
# nothing.
- uses: actions/checkout@v4
with:
submodules: recursive
# CMakePresets.json reads VCPKG_ROOT for the toolchain file. The runner
# has a vcpkg of its own, and this points at it.
- name: Point at the runner's vcpkg
shell: pwsh
run: echo "VCPKG_ROOT=$env:VCPKG_INSTALLATION_ROOT" >> $env:GITHUB_ENV
# vcpkg builds the manifest's packages at configure time and keeps the
# results in its binary cache, which is this folder. Keyed on vcpkg.json,
# so a run that changes no dependency restores the last one's binaries
# instead of building them again.
- name: Cache vcpkg's binaries
uses: actions/cache@v4
with:
path: ~/AppData/Local/vcpkg/archives
key: vcpkg-${{ runner.os }}-${{ hashFiles('vcpkg.json') }}
restore-keys: vcpkg-${{ runner.os }}-
# vcvars64.bat is what the x64 Native Tools Command Prompt runs: it puts
# cl, cmake, ninja and the Windows SDK's fxc, which compiles the engine's
# shader, on the path. vswhere finds it whichever edition the runner has.
- name: Find vcvars64
run: |
for /f "usebackq tokens=*" %%i in (`"%ProgramFiles(x86)%\Microsoft Visual Studio\Installer\vswhere.exe" -latest -products * -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 -property installationPath`) do echo VCVARS=%%i\VC\Auxiliary\Build\vcvars64.bat>> %GITHUB_ENV%
- name: Configure
run: |
call "%VCVARS%"
cmake --preset x64-debug
- name: Build
run: |
call "%VCVARS%"
cmake --build --preset x64-debug
# The game's tests and nothing of the engine's: the rules test, and the
# start-up check, which gets a Direct3D device on this runner.
- name: Test
run: |
call "%VCVARS%"
ctest --preset x64-debug

The checkout takes the submodule. Without submodules, external/labrador is an empty folder and configure stops at add_subdirectory. When the engine’s repository is private, or is a private fork, the checkout needs a token that can read it as well. A project that keeps the engine as plain files, as a starter project committed as it came does, has no submodule, and the line does nothing.

VCPKG_ROOT points at the runner’s vcpkg. Your CMakePresets.json reads it for the toolchain file, as it does on your machine, and the runner image comes with a vcpkg of its own in VCPKG_INSTALLATION_ROOT.

vcpkg’s binary cache is kept between runs. Configure builds the packages your vcpkg.json names, and keeps what it built in %LOCALAPPDATA%\vcpkg\archives, which the cache step saves and restores. The key is your vcpkg.json, so a run that changes no dependency restores the last one’s binaries and configures in seconds, and the first run, or one after a dependency changed, builds them, which took a little over a minute on a fast desktop and takes longer on a runner.

The MSVC environment comes from vcvars64.bat, the batch file the x64 Native Tools Command Prompt runs. It puts the compiler, CMake, Ninja and the Windows SDK’s fxc, the shader compiler the engine’s build calls, on the path. vswhere finds it in whichever Visual Studio edition the runner image has, and each step that runs CMake calls it first, because a step’s environment does not carry over to the next one.

Configure, build and test are the commands you type. The test step runs your project’s ctest, which holds your game’s tests and none of Labrador’s. The start-up check gets a Direct3D device on the runner, which has no GPU but still offers Direct3D an adapter.

Each push starts a run, listed under the repository’s Actions tab with its commit’s message: a yellow dot while it works, a green tick when it passes, a red cross when it fails. Click the run, then its windows job, to see each step above and its log. The first run of a project takes two to three minutes, because configure builds the vcpkg packages; later runs restore them and take under two. Watch GitHub build it goes through a run, and A failed run says how to find the error, what each failed step means, and how to run it again.

The runs are free for a public repository. A private repository’s come out of a monthly allowance, and a Windows runner’s minutes cost more of it than Linux’s: Build minutes has the figures.

The runner checks your repository out at D:\a\<repository>\<repository>, and the build’s object files sit far below that. Keep that folder under the 100 characters Choose a short folder asks for, which means a repository name under 40 characters; mygame is 6. One long enough to push the build’s paths past the compiler’s limit fails the Build step with fatal error C1083: Cannot open compiler generated file: '': Invalid argument, which Troubleshooting explains; rename the repository under its Settings to fix it.

Labrador’s own CI has a job that builds this project from the Get Started files against the engine, and it runs most of these steps: the runner’s vcpkg, vcvars found through vswhere, configure, build and the game’s ctest. That job takes the engine from the change being checked rather than from a submodule, and it restores the vcpkg binary cache the engine’s own Windows jobs save without ever saving one, so it does not run this file’s save step. The file itself has run, with the steps it has now, as the workflow of a repository of its own: matt439/labrador-mygame, which holds the project Start your own project builds, with Labrador at v0.2.0. On 26 October 2026 its first run found no cache, configured in 95 seconds, passed both tests and saved the cache, and the second restored it, so vcpkg restored its six packages instead of building them and configure took 42 seconds. That was a hit on the exact key; the restore-keys fallback, for a run after vcpkg.json changes, has not been exercised. Each run took about two and a half minutes on windows-latest, with MSVC 19.51. Both runs warn that actions/checkout@v4 and actions/cache@v4 target Node.js 20, which GitHub now runs on Node.js 24; nothing fails because of it.

That a starter project committed as plain files builds from a checkout was checked on 30 October 2026 by committing a starter project made from a development tree, cloning that commit into C:\dev\g8-author\a\mygame\mygame, a folder as deep as the runner’s, and running the workflow’s configure, build and test commands there, with Git’s line-end conversion on as on the runner; both tests passed. Such a project has not yet run the workflow on GitHub itself. On 31 October the comment above the checkout step, which had said the engine is a submodule, was reworded to cover such a project, after a reader following Put your project on GitHub found it false for theirs; the file’s steps are the ones that ran.

Documentation for Labrador v0.3.0. Built from Labrador 0f4f503 of 2026-11-03.

All documentation versions