How would you make CI prove that committed generated Go files match `go generate ./...` output?

## What the check is for Generated Go code is usually committed. That is a deliberate choice: it keeps `go build` free of a code-generation step, it lets readers and reviewers see what actually compiles, and it means a consumer of the repository needs no generator at all. The cost of committing it is that the committed copy can fall out of step with its inputs. Someone edits the source of truth, forgets to regenerate, and the repository now contains code that no longer corresponds to anything. The build is perfectly green, because the stale file compiles. The fix is a check that regenerates and compares. ## The shape of it ``` go generate ./... git add -A git diff --cached --exit-code ``` `git diff --exit-code` exits 1 when there is a difference and prints it, so the diff becomes the failure message. Two details in that snippet carry most of the value: - **Run it on a clean checkout.** The comparison is only meaningful if the tree started identical to the commit under test. In CI that is free; locally it is worth saying so in the docs. - **Stage before diffing.** A plain `git diff --exit-code` compares tracked files against the index and is blind to **untracked** files. A generator that emits a brand-new file therefore produces no diff and the check passes while the repository has an uncommitted artifact. `git add -A` first (or a `git status --porcelain` emptiness test) closes that hole. A third hole is worth checking once, by hand: if the generated files are listed in `.gitignore`, the check is vacuous — nothing is ever tracked, so nothing ever differs. A gate that cannot fail is worse than no gate, because people believe it. ## Making it deterministic The check compares bytes, so anything non-deterministic in the generated output turns it into a flaky gate that people learn to re-run. The recurring offenders: - **Timestamps and hostnames** written into a header banner. Remove them; the commit already records when and by whom. - **Absolute paths** from the machine that generated the file. - **Version strings** for the generator itself in the banner — harmless until the generator is upgraded, at which point every generated file in the repository churns. - **Ordering** that is not fixed. A generator that walks a map and emits in iteration order produces a different file each run, because Go randomises map iteration order. Sort before emitting. ## Making it version-stable The failure this gate produces most often is not stale code at all: it is **version skew**. Two things must match between the laptop and the pipeline. First, the **generators**. If each environment runs a differently-built copy of the same tool, the outputs differ and the diff blames whoever pushed last. Declaring the tools in `go.mod` so they are built from a pinned source removes this, and it turns an upgrade into a reviewable commit that carries the regenerated files with it. Second, the **Go release**. Anything that emits Go source usually formats it with the toolchain's formatter, and formatter output is not frozen forever — Go 1.19's reformatting of doc comments is the well-known example of a release that legitimately changed the bytes of correctly formatted files. A pipeline one release ahead of the laptops will therefore regenerate different bytes from identical inputs. Pin the Go version the same way you pin the tools, and treat a Go upgrade as a change that may carry a repo-wide regeneration commit. ## Triaging a red run When the gate fails on a pull request that touched nothing generated, work in this order: read the diff in the log — is it whole files, or one reformatted comment block? Compare the Go version and the tool versions between the two environments. Reproduce with the pipeline's toolchain. If the change is real and repo-wide, land it as its own commit, separate from feature work, so that reviewers can see a mechanical change for what it is. ## Why not have CI commit the result instead A tempting alternative is to let the job regenerate and push the result back to the branch. It looks friendlier and it is usually a mistake: it hides the drift instead of reporting it, it races with the author's own pushes, it can retrigger itself, and a bot commit lands code that no human reviewed on a branch that may have required checks. Failing with the diff in the log keeps the regeneration where it belongs — in the author's commit, under review, next to the change that caused it. ## The one-command rule Whatever the pipeline runs, an engineer must be able to run the identical command locally and see the identical result. A generation gate that can only be reproduced by pushing is the most expensive kind of check there is: every iteration costs a full pipeline round trip, and people respond by regenerating blindly until it goes green.