What Is a Build Matrix?
A build matrix produces a separate build for each combination of platforms, versions, or configurations you want to ship.
When software must run on many targets - several OSes, architectures, or runtime versions - you need a build per target. A build matrix declares the target dimensions once and CI generates a build job for every combination.
Build matrix vs test matrix
A test matrix verifies behavior across combinations; a build matrix produces shippable artifacts for each. They use the same matrix mechanism, but a build matrix usually uploads one artifact per cell for release.
A small example
A matrix of os: [linux, macos, windows] and arch: [x64, arm64] yields six builds, each producing a platform-specific binary you then publish as app-linux-arm64, app-macos-x64, and so on.
Naming artifacts per cell
Each cell must upload under a unique name derived from its matrix values; otherwise the second upload overwrites the first. Encoding the OS and arch into the artifact name keeps every target's output distinct.
Keeping it manageable
- Drop impossible or unneeded cells with
exclude. - Cache per-target so each cell still benefits from incremental builds.
- Limit dimensions to targets you actually ship.
Cross-compilation alternative
Sometimes you can cross-compile all targets from one runner instead of a matrix of native runners. That trades matrix breadth for a more complex toolchain - useful when native runners for a platform are scarce or slow.
Key takeaways
- A build matrix produces one artifact per target combination.
- It uses the same mechanism as a test matrix but emits shippables.
- Name artifacts uniquely per cell so uploads do not overwrite each other.