Continuous integration

Last reviewed: 2026-08-06. CI is a verification gate for the whole five-game tree; it does not require copyrighted game data to be committed.

Firestaff’s GitHub Actions workflow is defined in .github/workflows/verify.yml. It runs on pushes to main and on pull requests.

What the workflow checks

strict -Wall -Wextra -Werror compilation;
asset hygiene, hash validation and PO-layout checks without copyrighted game data;
CMake configure/build, CTest, the headless Phase A probe and the audio probe on Ubuntu, macOS and Windows;
deterministic world-hash comparison across the build platforms.

On macOS, the local CTest inventory also includes dm1_macos_real_data_boot. It runs the production DM1 M11 boot probe against the authenticated corpus under FIRESTAFF_DM1_MAC_DATA, FIRESTAFF_DATA, or ~/.firestaff/data. It is skip-safe when no licensed data is installed and does not extract or rewrite original files.

When the corpus contains the authenticated DM1 FM Towns package, the same gate also exercises --platform fm-towns. The probe covers both an extracted ISO tree and the packed ZIP/BIN source. For the packed case, the ISO members are decoded into bounded memory and passed to the original-format loaders; Firestaff does not create a second game-data tree.

For a manual macOS window-size check, pass --width and --height. Explicit dimensions select windowed mode and are reported by the boot-probe receipt as window=<width>x<height> windowMode=0; --fullscreen remains an explicit override. This covers both small and large native macOS host windows without treating macOS as an unverified historical DM1 source port.

The workflow uses a concurrency group for main and cancels an older run when a newer commit arrives. That is expected: always inspect the newest run for the current main SHA before treating a cancelled run as a failure.

Recent failure signatures

Lefthook installer fails during asset hygiene

The installer follows the Go version declared by the current Lefthook module. The workflow therefore pins the matching Go toolchain instead of relying on an older runner default. This job must install Lefthook and complete lefthook ci before the run is considered healthy.

`dm2_v1_decode_img9` is undefined during a CMake test link

This means a test target uses the DM2 GDAT loader without linking the IMG9 decoder translation unit. The fix belongs in the target’s CMake source list; do not add a stub implementation or weaken linker checks.

macOS Homebrew reports an untrusted tap

The SDL3 install step may print a Homebrew trust warning for an unrelated tap while still installing SDL3 successfully. The actionable result is the return status of brew install sdl3 and the following CMake build. Do not trust or untap unrelated taps in the repository workflow.

Local reproduction

cmake -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build --parallel
ctest --test-dir build --output-on-failure
SDL_VIDEODRIVER=dummy ./build/firestaff_m11_phase_a_probe

For a remote run, use the Actions page or:

gh run list --repo yeager/firestaff --branch main
gh run view <run-id> --repo yeager/firestaff --log-failed

The repository must not contain original game data. CI intentionally runs the asset checks with an empty data directory.

GitHub Pages renders the Markdown documentation as HTML with the workflow in .github/workflows/pages.yml. scripts/prepare_pages.py creates an ephemeral source tree, rewrites repository-relative links to the generated .html routes, and protects literal Liquid examples. The Jekyll build writes only to the Pages artifact; tracked Markdown sources remain unchanged.

Documentation changes should also update the cross-game status in PROJECT_STATUS.md and the page map in DOCUMENTATION_INDEX.md when a public claim changes.