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@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: submodules: recursive allow-unsafe-pr-checkout: false
# 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@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 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-debugCheck your browser build in CI adds an optional second workflow for the browser page and a downloadable tested runtime. Keep this native workflow alongside it; neither workflow publishes a website.
What 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. The starter’s Debug startup check can use the Direct3D WARP fallback on the runner.
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.
Earlier versions of this recipe ran 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 warned that
actions/checkout@v4 and actions/cache@v4 target Node.js 20, which GitHub now runs on
Node.js 24; neither run failed because of that warning.
The current development recipe uses reviewed immutable action commits and an explicit safe checkout input. It keeps the commands and cache choices above, but its new action versions await a fresh hosted run. The historical runs below qualify their tagged recipes; they do not qualify these new selectors. GitHub-hosted runners need Actions Runner 2.327.1 or newer for their Node 24 action runtime.
The released starter’s plain-file route also ran on GitHub on 16 November 2026. The
v0.3.0 starter ZIP was extracted without changing its files and committed as
9d004a4
in the dedicated public starter-proof repository.
Its first push’s run
passed on windows-latest, Windows Server 2025 with MSVC 19.51.36260. The windows job took
1 minute 48 seconds: configure 71 seconds, build 20 seconds, and both MyGameTests and
MyGameSmokeTests passed. It found no vcpkg cache, restored no packages and saved the new cache.
The ZIP’s workflow was the recipe before that action-selector update; this proof changed no engine source.
The Node.js 20 action warning above still appeared. Cache restoration for this plain-file
repository and the restore-keys fallback were not exercised by its first run.
Development documentation (unreleased). Built from Labrador aceb130 of 2026-11-20.