Your Go CLI ships prebuilt binaries — how do you pick the GOOS/GOARCH matrix and verify each artifact?

## Choosing the matrix A release matrix is a support promise, so it should come from evidence rather than from the length of `go tool dist list`. **Start with demand.** Where do users actually run the tool — developer laptops (macOS on arm64 and amd64, Windows on amd64), CI runners and servers (linux/amd64, increasingly linux/arm64), embedded or edge devices (32-bit arm)? Download counts, issue reports and the platforms your own infrastructure runs on are all better inputs than guesswork. **Then apply the toolchain's own tiering.** The Go project designates a small set of ports as *first class*: they are tested continuously, a broken build on one blocks a Go release, and official binary downloads exist for them. Linux, macOS and Windows on the mainstream architectures are in that group. Other ports in `go tool dist list` are real and usable, but they are best-effort — if something breaks on one, you are likely to be the person who finds it and files the bug. That is a fine trade for a platform your users need; it is not a reason to publish forty artifacts nobody downloads. **Validate every pair mechanically.** Keep the matrix in one place in the build configuration and check each entry against `go tool dist list` output rather than trusting a hand-written list. An invalid pair fails the build loudly, but a *valid but unintended* one — a typo that happens to name a real port — just produces a download nobody can use. ## Building the matrix Cross-building is the reason the matrix is cheap: one machine, one checkout, `GOOS` and `GOARCH` set per invocation, no per-platform runner and no emulation required to produce the artifacts. Set the pair explicitly for every entry, including the one that matches the build host, so nothing silently inherits host defaults. Name artifacts so users and installer scripts can pick correctly — the tool name plus `GOOS` and `GOARCH`, with `.exe` appended for Windows by the go command — and publish checksums alongside them. Leave microarchitecture baselines alone. A public binary built with a raised `GOAMD64` runs fine on your build machine and on modern CI, then dies with an illegal-instruction fault on some user's older laptop, with a stack trace pointing into the standard library. Tuned baselines belong to internal artifacts on hardware you know. ## Verifying what you built This is the part teams skip, and it is where the leaf's real failure lives: a binary that runs on the build machine and faults on the target. **Check the artifact's identity.** Run `file` (or the platform equivalent) on each produced binary and assert that it reports the operating system and architecture you asked for — an ELF for Linux naming aarch64, a Mach-O for macOS, a PE for Windows. This is a two-second check that catches the whole class of "one matrix entry didn't take": a shell quoting mistake, a variable that was not exported, a job that reused a cached artifact. Automate the assertion; do not eyeball it. **Then actually run it.** A successful cross-build proves the package compiles and links for the target and nothing more. It does not prove the platform-specific file you added behaves, that a path or permission assumption holds, or that the CPU baseline is satisfied. A minimal smoke test — start the binary, print its version, exit zero — on real hardware or an emulator for each architecture is enough to catch nearly all of it. Where a real runner does not exist for an architecture, an emulated container is a reasonable substitute; note in the release process which platforms are verified only by emulation. **Test where the code branches by platform.** Files selected by `GOOS` suffix are compiled only for their platform, so an error in one is discovered by the first build that targets it. Cross-building every supported pair in CI, not just the host, turns that latent breakage into a failed build minutes after the commit. ## Retiring entries A matrix only grows unless someone prunes it. Each entry costs build time, storage, release-note surface and an implied support promise. Drop a platform when downloads and issues both say nobody is using it, announce it in the release notes, and keep the source buildable for it even after you stop publishing a binary — users who need that port can still build from source, which is exactly the escape hatch Go's easy cross-compilation gives you.