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:
# 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-debugWhat each step is for
Section titled “What each step is for”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.
See it run
Section titled “See it run”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.
Keep the path short
Section titled “Keep the path short”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.
What has been checked
Section titled “What has been checked”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.