Before cutting a release built offline from vendor/, how do you prove the vendored tree matches go.mod?

## The scenario The release build runs on a machine with no network access. That is the whole reason the repository carries `vendor/`: everything the compiler needs is in the commit, so the artifact can be produced from a checkout and nothing else. The question a release engineer has to answer before pressing the button is not "does it build" — it will — but **"is what is in `vendor/` actually the dependency set `go.mod` declares?"** ## Two failure modes, only one of which the toolchain catches **The loud one.** `vendor/modules.txt` and `go.mod` disagree: a module required but not marked explicit, a module marked explicit but no longer required, or a version mismatch. The `go` command performs this comparison before compiling and stops with `go: inconsistent vendoring`, listing every offender. You cannot miss it, and you cannot ship past it. **The silent one.** The index and `go.mod` agree perfectly, but the *files* are not what those versions contain. This happens more often than people expect: - someone patched a dependency bug by editing a file under `vendor/` and committed it; - a merge conflict in the vendored tree was resolved by hand, badly; - a commit included `vendor/modules.txt` and `go.mod` but only some of the moved source files; - a regeneration was run on a machine that could not reach some modules, producing an incomplete tree that still indexes consistently. None of these fail the build. The `go` command compares the index against `go.mod` and stops there; it does not re-hash the vendored source, because in vendor mode that source *is* the input, not a cache of something verifiable. A one-line edit compiles exactly like the original and leaves no trace outside version-control history. ## The check that closes the gap Because the only authority on what those versions contain lives outside the repository, verification requires a machine that can reach the module sources. There the check is simple and mechanical: ``` go mod vendor git status --porcelain vendor ``` `go mod vendor` resets the directory from `go.mod`, so if the committed tree was faithful, the regeneration produces byte-identical files and version control reports nothing. Any output at all — a modified file, an untracked file, a deletion — is drift, and the output itself names exactly which package drifted. This is the diagnostic, and it doubles as the fix: the same command that detects the problem has already corrected it on disk. You commit the result. ## Where to run it Run it on **every pull request**, not at release time. The regeneration check is cheap, and its value collapses if you defer it. Caught on the PR that introduced it, drift is a two-line diff with an obvious author and an obvious cause. Caught at release, it is an unexplained difference somewhere in a tree of tens of thousands of lines, discovered by the person least able to say whether the edit was deliberate. A release-time run is still worth having as a backstop, because branches merge and CI configurations change. ## Making the check trustworthy Two things make this check misbehave, and both are worth pre-empting. **Toolchain skew.** The tree is generated by a specific `go` version, and different versions can write slightly different output — annotations in `modules.txt` in particular. If CI regenerates with a different toolchain than the developers use, the check reports drift on every commit and gets disabled within a week. Pin the toolchain the check runs with. **A silent partial fetch.** If regeneration cannot reach some module and the command fails, do not let the pipeline continue to the `git status` step and conclude that nothing changed, or worse, that a truncated tree is correct. Fail the job on the regeneration command's own exit status first. ## What this does and does not prove It proves the committed tree is what `go mod vendor` produces from the current `go.mod` **on the machine that ran the check, at that moment**. That is a strong property and the right one for a release gate. It is not an independent audit of the dependencies themselves — it says the tree matches the declared versions, not that those versions are safe, and not that the vendored copies came from a source you trust more than the one CI reached. Vendoring moves the trust decision to the moment of regeneration; the check just makes sure nothing has moved since. ## The payoff With the check in place, the offline property is real: any commit on the release branch can be rebuilt on an isolated machine, months later, with no dependency on any remote host still serving those versions. That guarantee is the entire reason to carry `vendor/`, and without a regeneration check it is a guarantee about a directory nobody has verified.