Your onboarding script installs Go tools with go install, and every machine ends up with a different build. Why, and how do you fix it?

## The symptom A repository has a `setup.sh` that a newcomer runs on day one. It installs a handful of developer commands with `go install`. Six months in, no two laptops agree: one person's generator emits different output, another's checker reports findings nobody else sees, and the script has not changed in either case. The script is deterministic; the thing it invokes is not. ## Cause one: @latest is resolved when it runs `go install example.com/cmd/mytool@latest` asks, at that moment, for the newest release of that module. The answer depends entirely on the calendar. Every machine gets "the latest", which is not a version — it is a query. Two developers running byte-identical scripts weeks apart install different software, and neither script nor repository says which. The fix is unglamorous and complete: **name the version**. ``` go install example.com/cmd/[email protected] ``` Now the version is text in a file. It is greppable, reviewable in a pull request, and it changes only when someone decides it should. Upgrading becomes a commit — with the behaviour change attributable to it — instead of an invisible consequence of when you joined the team. ## Cause two: nothing in the project records the tool The `pkg@version` form of `go install` deliberately builds in an isolated module context: it does not read your `go.mod`, does not write it, and takes its dependency versions from the tool module's own requirements. That isolation is what stops a code generator from bumping a library in your service — genuinely valuable — but it has a direct consequence: **your repository knows nothing about the tools you installed**. There is no lock file for them and no command that reports "the versions this project expects". So the recording has to be something you create. A single file listing every tool and its exact version, consumed by the setup script, is enough. What matters is that exactly one place names each version and that a reader can find it. ## Cause three: the destination is inherited, not chosen `go install` writes to `$GOBIN`, or `$GOPATH/bin` when GOBIN is empty, defaulting to `~/go/bin`. Across a team, some machines have GOBIN set to something bespoke, some have an old GOPATH from a pre-modules era, and some have a stale binary of the same name earlier on PATH. The result is a script that appears to succeed while the command a developer actually runs comes from somewhere else. Make it explicit in the script: - set `GOBIN` yourself so every machine lands in the same place; - print `go env GOBIN GOPATH` in the script's output, so a failed setup is diagnosable from a pasted log; - have the script check that the destination is on PATH and say so plainly if it is not, rather than leaving the newcomer with `command not found`. A repository-local bin directory works well: it cannot collide with anything the developer installed for other work, and deleting it resets the environment completely. ## Diagnosing a machine that is already wrong - `go env GOBIN GOPATH` — where the go command will write, which is the first question to settle. - The shell's own lookup (`command -v mytool`) — whether the binary being run is the one that was just installed or an older copy earlier on PATH. - `go install -n <the exact line from the script>` — prints the commands the go command would run without running them, which shows whether the step is doing what the script author believed. The order matters: confirm the destination, then confirm which copy is being executed, and only then argue about versions. ## What good looks like An onboarding script whose tool section is one loop over a reviewed list of `module/[email protected]` lines; an explicit `GOBIN` that the script also verifies is on PATH; and a printed summary of what it installed and where. Re-running it on an existing machine produces the same result as running it on a fresh one — which is the property you are actually testing when you wipe a laptop and follow your own README. ## The judgement being assessed Anyone can say "pin the version". The senior signal is knowing **why** the pin has to live in your repository rather than being derivable from it: the version form of `go install` is isolated from your module by design, so reproducibility here is something you build, not something the go command gives you. The second signal is treating the install destination and PATH as part of the contract, because a correct install nobody can execute is indistinguishable from a failed one.