TUN-11024: Build with the exact Go version from go.mod

The macOS binaries in the latest VULN-181166 patch release were built
with an older Go than the other platforms. install-go.sh ran
`brew install go@X.Y.Z`, which is not a Homebrew formula, and the
script had no `set -e`, so the install failed silently and the build
used whatever Go the runner already had.

GOTOOLCHAIN=auto, the default, only upgrades an older local Go to the
go.mod version and never downgrades a newer one. The Makefile now
exports GOTOOLCHAIN=go<version> from the go directive in go.mod, so
every build that goes through make (Linux, macOS, Windows, packaging
and Docker images) uses exactly that version, downloading it when the
installed Go differs. A go directive without a patch version fails
the build, because go1.X is not a valid toolchain name.

Remove install-go.sh and MAC_GO_VERSION, since the macOS runner now
only needs some Go installed. Key the macOS cache on go.mod instead of
GO_VERSION, and drop the job's silent exit when the build script is not
executable.

Document the full major.minor.patch requirement and the Go upgrade
checklist in README and AGENTS.md.

Closes TUN-11024

Author: DevinCarr

.ci/mac.gitlab-ci.yml

@@ -10,8 +10,9 @@ include:
     GOPROXY: "https://proxy.golang.org,direct"
   cache:
     key:
-      prefix: "$CI_COMMIT_REF_PROTECTED-$GO_VERSION-$TARGET_ARCH"
+      prefix: "$CI_COMMIT_REF_PROTECTED-$TARGET_ARCH"
       files:
+        - go.mod
         - go.sum
     paths:
       - .cache/go/
@@ -34,14 +35,10 @@ macos-build-cloudflared: &mac-build
     paths:
       - artifacts/*
   script:
+    - set -euo pipefail
     - ARCH=$(uname -m)
     - echo ARCH=$ARCH - TARGET_ARCH=$TARGET_ARCH
-    - ./.ci/scripts/mac/install-go.sh "$MAC_GO_VERSION"
-    - BUILD_SCRIPT=.ci/scripts/mac/build.sh
-    - if [[ ! -x ${BUILD_SCRIPT} ]] ; then exit ; fi
-    - set -euo pipefail
-    - echo "Executing ${BUILD_SCRIPT}"
-    - exec ${BUILD_SCRIPT}
+    - ./.ci/scripts/mac/build.sh
 
 ###############################################
 ### Build and Sign Cloudflared Mac Binaries ###

.ci/scripts/mac/install-go.sh

@@ -1,6 +1,5 @@
 variables:
   GO_VERSION: "1.27.3"
-  MAC_GO_VERSION: "go@$GO_VERSION"
   WIN_GO_VERSION: "go$GO_VERSION"
   GIT_DEPTH: "0"
   # Athens caches public modules for faster CI downloads; direct preserves public fallback.

.gitlab-ci.yml

@@ -289,6 +289,13 @@ notice, do not proceed without explicit confirmation.
 ## Dependencies Management
 
 - Use Go modules (`go.mod`) exclusively
+- The `go` directive in `go.mod` must include the patch version (`major.minor.patch`).
+  It is the exact Go version for builds and tests: the Makefile exports
+  `GOTOOLCHAIN=go<version>` from it unless Go is configured with `GOTOOLCHAIN=local`.
+  Cloudflare's internal Go package sets that so its patches are never replaced by an
+  upstream toolchain (RFC-028); never override it. Do not add a `toolchain` directive.
+  When bumping Go, align all CI, Docker image, and documentation version references,
+  including the Linux CI builder image and digest; see README's "Updating Go" section.
 - Resolve dependencies from the locked module graph with `go mod download`; do not vendor dependencies.
 - Builds, tests, vet, and lint use `-mod=readonly`; `go.mod` and `go.sum` must not drift in CI.
 - Linux CI uses Athens before public and direct module sources; macOS and Windows use the public proxy directly.

AGENTS.md

@@ -40,6 +40,16 @@ ifdef CONTAINER_BUILD
 	VERSION_FLAGS := $(VERSION_FLAGS) -X "github.com/cloudflare/cloudflared/metrics.Runtime=virtual"
 endif
 
+# Build and test with exactly the Go version in go.mod. The default GOTOOLCHAIN=auto
+# only upgrades an older local Go and never downgrades a newer one.
+# Leave GOTOOLCHAIN=local alone if an environment sets it in go.env.
+ifneq ($(shell go env GOTOOLCHAIN),local)
+    GO_MOD_VERSION := $(shell go list -m -f "{{.GoVersion}}")
+    ifneq ($(GO_MOD_VERSION),)
+        export GOTOOLCHAIN := go$(GO_MOD_VERSION)
+    endif
+endif
+
 LINK_FLAGS :=
 ifeq ($(FIPS), true)
 	export GOFIPS140 := latest

Makefile

@@ -75,6 +75,23 @@ For example, as of January 2023 Cloudflare will support cloudflared version 2023
   - [golangci-lint](https://github.com/golangci/golangci-lint)
   - [gomocks](https://pkg.go.dev/go.uber.org/mock)
 
+### Updating Go
+
+The `go` directive in `go.mod` must specify the full `major.minor.patch` version
+(for example, `go 1.27.3`). Do not omit the patch version, including `.0` releases.
+This is the exact Go version used to build and test cloudflared: the Makefile exports
+`GOTOOLCHAIN=go<version>` from it, so `make` downloads that toolchain whenever the
+installed Go is older or newer. Tools that `make` runs with `go run pkg@version` also
+use this toolchain. A `toolchain` directive in `go.mod` is ignored; do not add one.
+To use the installed Go instead, run `make <target> GOTOOLCHAIN=local`.
+
+When upgrading Go, update the `go` directive and all corresponding version references
+in `.gitlab-ci.yml`, `.ci/image/Dockerfile`, `.github/workflows/check.yaml`, and the
+Dockerfiles. Update the Linux CI builder image and digest in `.ci/linux.gitlab-ci.yml`
+to match; its `golangVersion` selects the major/minor image family. On macOS and
+Windows a mismatch only costs a toolchain download. Builds that use `GOTOOLCHAIN=local`
+fail if their Go is older than `go.mod` and use their own Go if it is newer.
+
 ### Build
 To build cloudflared locally run `make cloudflared`