proposal: cmd/go: Add support for the `GOTOOLCHAIN` option to respect the runtime version specified in the `toolchain` directive of the go.mod file

[moznion]

Proposal Details

Currently, the local Go runtime determines the actual Go version to use by checking the toolchain directive in the go.mod file when GOTOOLCHAIN=auto is set. If the local Go runtime is newer than the version specified in the toolchain directive, it defaults to the local Go version. This behavior aligns with the Go Toolchain documentation.

However, in some cases—such as in production environments—it may be necessary to enforce a specific Go runtime version, even though Go maintains strong forward and backward compatibility. For example, if the toolchain directive specifies 1.22.8 but the Go runtime in the container is 1.23.2, the actual version used would be 1.23.2. This could lead to unexpected issues if the container runtime is updated (even toolchain is never changed), which should sometimes be blocked to prevent unexpected factors.

While setting GOTOOLCHAIN=<version> is a valid solution but usually this GOTOOLCHAIN environment variables might be in disorder in a project; this is against the DRY principle. I believe it would be more convenient to have an option that always respects the version specified in the toolchain directive as the actual runtime version. This would allow developers to control the Go version for an application simply by modifying the version in the toolchain directive.

As a potential solution, how about introducing an option like GOTOOLCHAIN=mod to achieve this behavior?

[gabyhelp]

Related Issues and Documentation

• extending Go forward compatibility
• extended forwards compatibility for Go #57001 (closed)
• cmd/go: toolchain directive in go.mod being updated unnecessarily #65847
• Forward Compatibility and Toolchain Management in Go 1.21 > Toolchain Management
• Go Toolchains > Go toolchain selection
• Go Toolchains > Introduction
• cmd/go: implement GOTOOLCHAIN=auto
• cmd/go: GOTOOLCHAIN=version+auto doesn't use the named version in go install package@version #69051
• Go Modules Reference > go.mod files > toolchain directive
• go run not adhering to toolchain of go.mod when specifying package version #69817 (closed)

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}