CI Build Triggers (commit-message opt-ins)

CI Build Triggers (commit-message opt-ins)#

These lanes live in CONSUMER repos, not here. ContainerHub’s own CI is ubuntu24.04.yml (preflight + docs), windows-scripts.yml (PowerShell lint/tests), and two scheduled housekeeping workflows — none of them builds a container image, and none reacts to the tokens below. This page documents the convention the consuming application repos use with the images published from here.

Not every CI lane runs on every push. The heavier lanes are opt-in per commit via magic tokens in the commit message, so routine work does not spend Windows-runner minutes or cross-compile time it does not need. The token is matched against github.event.head_commit.message, so it must be in the pushed HEAD commit’s message (not an earlier commit in the push).

Lane

Trigger

Default

Linux x86_64 (build + test + coverage)

always, on push/PR to main/develop

runs every time

Windows (MSVC/clang-cl container build)

[build-win] in the commit message

skipped

Linux ARM64

[build-arm] in the commit message

skipped

Usage#

Add the token anywhere in the commit subject or body:

git commit -m "fix(shadows): correct the cascade split maths [build-win]"

Combine them to run both extra lanes from one push:

git commit -m "build: verify the toolchain on every target [build-win][build-arm]"

Consequences worth knowing#

  • A green checkmark without [build-win] says nothing about Windows. The Windows workflow reports skipped, which reads as success at a glance but means it never ran. If a change touches the Windows build (CMake, clang-cl flags, the container image, anything under windows/), push at least once with [build-win] before trusting it. Same for ARM and [build-arm].

  • The token is on the HEAD commit only. If you push a batch, only the last commit’s message is checked. Amend or add an empty trigger commit (git commit --allow-empty -m "ci: run windows [build-win]") if the token landed on an earlier commit.

  • These gates predate the current work and are a deliberate runner-cost decision. Whether the Windows lane should be opt-in, or run on PRs to main / nightly, is an open question tracked in the main repo’s BACKLOG.md under “CI and release gaps”.

See also github-cli-pipeline-monitoring.md for reading lane status with gh (including telling a real pass from a skipped gate).