Explicitly set GOTOOLCHAIN environment variable

[atc0005]

Overview

In short, Go 1.21 and newer automatically download a newer Go toolchain when building code that has been explicitly marked as requiring a newer Go toolchain.

Overview from the official docs:

Starting in Go 1.21, the Go distribution consists of a go command and a bundled Go toolchain, which is the standard library as well as the compiler, assembler, and other tools. The go command can use its bundled Go toolchain as well as other versions that it finds in the local PATH or downloads as needed.

The choice of Go toolchain being used depends on the GOTOOLCHAIN environment setting and the go and toolchain lines in the main module’s go.mod file or the current workspace’s go.work file. As you move between different main modules and workspaces, the toolchain version being used can vary, just as module dependency versions do.

In the standard configuration, the go command uses its own bundled toolchain when that toolchain is at least as new as the go or toolchain lines in the main module or workspace. For example, when using the go command bundled with Go 1.21.3 in a main module that says go 1.21.0, the go command uses Go 1.21.3. When the go or toolchain line is newer than the bundled toolchain, the go command runs the newer toolchain instead. For example, when using the go command bundled with Go 1.21.3 in a main module that says go 1.21.9, the go command finds and runs Go 1.21.9 instead. It first looks in the PATH for a program named go1.21.9 and otherwise downloads and caches a copy of the Go 1.21.9 toolchain. This automatic toolchain switching can be disabled, but in that case, for more precise forwards compatibility, the go command will refuse to run in a main module or workspace in which the go line requires a newer version of Go. That is, the go line sets the minimum required Go version necessary to use a module or workspace.

The intent behind the images provided by this project are two fold:

• build code using a specific Go release version for CI purposes
• generate release assets using a specific Go release version

In both cases the very specific version of Go used is intentional. If I generate a project release after having tested against Go 1.21.1 I don't want to generate assets using Go 1.21.2 instead.

Likewise for CI use I want to fail the build fast if there is a hard version requirement that we're not meeting.

The official docs provide a way to set this expectation:

When GOTOOLCHAIN is set to local, the go command always runs the bundled Go toolchain.

To set user-specific expectation:

go env -w GOTOOLCHAIN=local

References

• https://go.dev/doc/toolchain
• proposal: set GOTOOLCHAIN=local (or =path) in our image docker-library/golang#472
• Set GOTOOLCHAIN to prevent go auto-upgrade docker-library/golang#491
• update to go1.21.1, default to GOTOOLCHAIN=local moby/moby#46069
• Update supported Go range to 1.19 - 1.21 opencontainers/image-spec#1114
• extended forwards compatibility for Go golang/go#57001
  • cmd/go: extended forwards compatibility for Go [1.19 backport] golang/go#61197
  • cmd/go: extended forwards compatibility for Go [1.20 backport] golang/go#61198

See also:

• cmd/go: Go modules initialised by go1.21.1 cannot be built using go1.20.8 golang/go#63279
• cmd/go: go get -u && go mod tidy behaves differently starting with Go 1.21.0, leading to unknown directive toolchain errors golang/go#62409