Workflows

All configuration happens through with: inputs on the three workflow_call workflows. There are no config files, and the only environment contract for callers is BUILD_VERSION, exported to pre-build and source-prepare hooks. binary_name is required everywhere; every other input has a default.

zig-ci.yml#

Runs tests, then a ReleaseSmall cross-build per matrix target. Requires permissions: contents: read.

Hook order within each matrix job: setup_command → pre_test_command → tests → pre_build_command → build → e2e_command (matching target only). Each hook command reaches bash -euo pipefail through an environment variable, so its text is never templated into the workflow YAML. The build cache covers .zig-cache and ~/.cache/zig, keyed on your Zig sources, build.zig, build.zig.zon and vendor/.

Every job appends a summary table: tests passed, test MaxRSS, and ReleaseSmall binary size in MB and bytes.

zig-nightly.yml#

Builds the full 12-target matrix on a schedule. Requires permissions: actions: read and contents: read (plus contents: write in the caller if publish_release is on).

A preflight job fetches the repository's workflow runs from the GitHub API and hands them to a small Zig program that looks for a previous successful run of the same workflow (scheduled or manually dispatched) on the same commit; on a match the build is skipped unless force is set. Nightly versions look like nightly-YYYYMMDD-<short-sha> and are injected via -Dversion.

Each nightly binary is packaged with a .sha256 checksum file and a manifest-<target>.json recording built_at, commit, run_id, run_url, target, zig_target and version. With publish_release: true, the workflow replaces the assets of the rolling prerelease on each run and retargets its tag.

zig-release.yml#

Triggers on v* tag pushes in the caller. Requires permissions: contents: write; add packages: write only when publish_docker is enabled. It does not require caller repository secrets.

The version is taken from the tag with the v stripped and injected as -Dversion. Release assets are named <prefix>-<target>.bin (or .exe on Windows, which additionally gets a .zip). If a release for the tag already exists, its assets are updated instead of failing.

With publish_docker: true, a follow-up job builds linux/amd64 and linux/arm64 images with buildx + QEMU, pushes to ghcr.io/<owner>/<repo> with the semver tag and latest, and uses GitHub Actions layer caching.

Composite actions#

Three helpers live under .github/actions/. At the reviewed snapshot, the reusable workflows still reference them through the mutable v1 branch; pinning the caller workflow alone therefore does not yet make the complete internal chain immutable:

nightly-decide and package-artifact are written in Zig — seven zig test blocks between them — and tested in NullBuilder's own CI on every push and pull request.