How do you stamp a Go binary so a postmortem can prove which build was running?

## The question a postmortem actually asks Something went wrong at 03:14. You have logs, a core of metrics, and an artefact. Before any analysis is worth anything you have to answer: *which build produced this behaviour, and what source was it?* Deployment records and image tags are evidence, but they are evidence about the deployment system, not about the binary. The binary should be able to answer for itself. Go gives you two independent stamps, and they fail in different ways, which is exactly why you want both. ## Stamp one: what you inject `-ldflags -X` writes strings into package-level variables at link time. The pipeline computes the version and the short commit sha and injects them: go build -ldflags "-X main.version=$VERSION -X main.commit=$COMMIT" -o daemon . This stamp is *for humans and for correlation*. It belongs in three places: 1. **One structured log line at start-up**, so any log query that finds the incident also finds the build. 2. **A `--version` flag**, so anyone holding the artefact can ask it directly. 3. **A small endpoint or metric label**, so monitoring can show a rollout in progress as two versions running side by side. Its weakness is that it is whatever the pipeline decided to write. It can be stale, it can be duplicated across two builds, and it can be attached to a tree that did not match. It is a label, not proof. ## Stamp two: what the toolchain records When `go build` links an executable from a package inside a version-controlled directory, the go command records version-control information into the binary's embedded build settings: the revision, the commit time, and whether the working tree was modified. The `-buildvcs` flag controls this, and the default behaviour includes the information when it is available. This stamp is *machine-produced from the checkout that was actually compiled*, which is what makes it useful as evidence. Nobody typed it. Its weakness is availability. In container builds it very often disappears, for two reasons: the version-control metadata directory was not copied into the build context, so there is nothing to read; or the pipeline explicitly passed `-buildvcs=false`, commonly because the version-control tool refused to report status inside the container and the build failed until someone turned it off. Either way the resulting images carry no revision at all — and you find out during the incident, which is the worst possible time. Run `go version -m` against a real production image once, deliberately, and see what is actually there. ## Reading the stamps back **From the file, without running it:** `go version -m ./daemon` prints the Go toolchain version, the module path, the dependency modules, and the recorded build settings — `GOOS`, `GOARCH`, `CGO_ENABLED`, the build mode, and the `vcs.*` entries. This works on a binary pulled out of an image, off a node, or out of an artefact store, and it does not require executing an artefact you may not trust. **From inside the process:** `runtime/debug.ReadBuildInfo` returns the same information to the running program, which is how a service can log its own recorded revision alongside its injected version, and how a `/version` handler can report both. ## The trap: vcs.modified `vcs.modified=true` means the working tree had uncommitted changes when the build ran. The revision is then a starting point rather than an identity: the source that produced the binary is not the source at that revision, and nobody knows exactly how it differed. For a release artefact this should be treated as a defect in the pipeline, not a curiosity. The usual cause is a build step that writes into the checkout before compiling. Fix it so that release builds are always clean, and the stamp becomes something you can rely on under pressure. ## Putting it together A defensible posture for a service you will one day have to write a postmortem about: - Inject version and commit; default them to a visible sentinel so an un-stamped build is obvious. - Log both injected values and the recorded revision in one start-up line, and expose them on demand. - Keep version-control stamping working in the container build rather than silencing it, and verify that on a real image. - Gate the release on the artefact: run the freshly built binary, check that it reports a real version, and check that the recorded revision is present and the tree was clean. The cost of all of that is a few lines in a build script. The cost of not having it is an incident where the first hour goes on establishing what was running.