Continuous integration¶
GitHub Actions builds, tests and publishes every push to main and every pull request. The layout follows the habit of large open-source engines: runner.yml is the entry point and calls one workflow per concern, and each of those can also be started by hand from the Actions tab.
| Workflow | What it does |
|---|---|
runner.yml |
the entry point: static checks first, then the three platforms and the docs in parallel |
static_checks.yml |
the DCO sign-off of every commit of a pull request, no CRLF or trailing whitespace, Git LFS pointers (git lfs fsck --pointers), and actionlint on the workflows |
linux_builds.yml |
Tests: Release build and every test project, GPU tests on lavapipe (Mesa's software Vulkan) with the validation layer, the bindings generator's tests with libclang. NativeAOT: ./build.sh aot, the Luau tests and a fixture game from the published binary, rendered offscreen, shipped as a pack and without the shader compiler |
windows_builds.yml |
Tests: Release build and every test project. NativeAOT: the publish, the Luau tests and the fixture game, with no GPU |
macos_builds.yml |
Apple silicon and Intel: Release build, the tests (the Metal GPU tests skip unless the runner's GPU qualifies), the NativeAOT publish and the fixture game, uploaded as artifacts. The Intel job is experimental while a rare crash is investigated (see Help wanted) |
docs.yml |
./build.sh docs (the API reference, then mkdocs build --strict); on a push to main, publishes the site to the apogeeengine/docs repository's GitHub Pages |
thirdparty_*.yml |
manual workflows that build the vendored binaries we cannot take from upstream (GameNetworkingSockets, OpenAL Soft, SDL for Linux). Their recipes and the checksums are in ThirdParty/README.md |
.github/actions/setup is the part the build workflows share: the Git LFS objects of the platform (cached by object id, so a push does not spend the repository's LFS bandwidth), the .NET SDK and the native libraries (Flecs, Luau, and so on).
Rules the workflows hold to¶
- Tests are not samples. CI runs
Tests/and the fixture game inTests/Fixtures; nothing runsSamples/, no test depends on one, and there are no reference screenshots of samples. - Required natives fail, they do not skip.
APOGEE_REQUIRE_NATIVElists the native libraries that must load on each platform;APOGEE_REQUIRE_VULKAN,APOGEE_REQUIRE_CLANGandAPOGEE_REQUIRE_METAL_COMPILERdo the same for the GPU, libclang and Apple's shader compiler. - Run what CI runs.
./build.sh testisdotnet test, and./build.sh aotis the publish step: the same commands a developer uses.
Reproducing a failure¶
Linux needs mesa-vulkan-drivers and vulkan-validationlayers for the GPU tests (lavapipe is the software device). Windows and macOS runners have no usable Vulkan or Metal device: a GPU test that skips there ran on Linux.