educates-upgrade-go

name	educates-upgrade-go
description	Upgrade the Go version across the entire educates-training-platform project. Invoke when asked to "upgrade go version", "bump golang", "update go", or "use go 1.xx". Updates go.work, all go.mod files, all Dockerfiles, and CI/CD workflow files.
argument-hint	<new-go-version> (e.g. 1.24)
allowed-tools	Read, Edit, Glob, Bash

Educates Go Version Upgrade Protocol

Upgrade the Go version to $ARGUMENTS (e.g. 1.24) across all files in the project.

Step 1: Find the Current Version

Check the current Go version before making changes:

grep -rn "^go 1\." go.work client-programs/go.mod installer/operator/go.mod node-ca-injector/go.mod assets-server/go.mod

Step 2: Update All Files

You must update all of the following. Do not skip any.

Go Module Files

• go.work — update the go 1.xx directive. The workspace covers client-programs/, installer/operator/, and node-ca-injector/.
• client-programs/go.mod — update the go 1.xx line
• installer/operator/go.mod — update the go 1.xx line (the kubebuilder operator)
• node-ca-injector/go.mod — update the go 1.xx line
• assets-server/go.mod — update the go 1.xx line (Docker-only module, not in go.work)

Discover every module so none is missed (the platform modules are at the repo root; ignore any go.mod under workshop-samples/, which is sample workshop content with its own lifecycle):

git ls-files 'go.mod' '*/go.mod' | grep -v '^workshop-samples/'

Note: tunnel-manager is a Python (uv) component and has no go.mod.

Dockerfiles

Use the plain golang:1.xx image tag — do not switch to Alpine, Buster, Trixie, or other derivative tags. Only the golang:1.xx version changes — do not add or remove the --platform=$BUILDPLATFORM prefix as part of a version bump.

• client-programs/Dockerfile — FROM --platform=$BUILDPLATFORM golang:1.xx AS builder
• installer/operator/Dockerfile — FROM --platform=$BUILDPLATFORM golang:1.xx AS builder
• node-ca-injector/Dockerfile — FROM --platform=$BUILDPLATFORM golang:1.xx AS builder
• assets-server/Dockerfile — FROM --platform=$BUILDPLATFORM golang:1.xx AS builder
• workshop-images/base-environment/Dockerfile — FROM --platform=$BUILDPLATFORM golang:1.xx as builder-image

Search for any other Dockerfile referencing golang:

grep -rn "FROM .*golang:" --include="Dockerfile*" .

About --platform=$BUILDPLATFORM

It is not a standalone flag — it is correct only as a three-part cross-compile set in the same stage:

1. FROM --platform=$BUILDPLATFORM golang:1.xx AS builder (builder runs on the build host, not emulated),
2. ARG TARGETOS / ARG TARGETARCH,
3. ... GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build ... (cross-compile to the target).

With all three, a multiarch build cross-compiles natively instead of running the Go toolchain under QEMU for each non-native arch — much faster. Adding the prefix to a stage that builds with a plain go build (no GOOS/GOARCH) produces a wrong-architecture binary — so the prefix and the GOOS/GOARCH build must always go together.

All five Go Dockerfiles above currently cross-compile and carry the prefix. If you ever add a new Go build stage, give it the full three-part set (or no --platform at all) — never the prefix alone.

CI/CD Workflows

The Go workflows (.github/workflows/*.yaml — note the extension) pin the toolchain with actions/setup-go using go-version-file: pointing at a module's go.mod (e.g. client-programs-ci.yaml → client-programs/go.mod, installer-operator-ci.yaml → installer/operator/go.mod). Because the version is read from go.mod, bumping the go.mod files above is normally enough — no hardcoded version to edit.

Still confirm there's no stray hardcoded version left behind:

grep -rnE "go-version:|golang:1\." .github/workflows/

If any go-version: '1.xx' literal exists, update it (or, preferably, convert it to go-version-file:).

Step 3: Verify

Run in order, fix any failures before proceeding:

1. Sync dependencies in every module (run go mod tidy in each):

for m in client-programs installer/operator node-ca-injector assets-server; do
  (cd "$m" && go mod tidy)
done

2. Build the CLI and the operator:

make build-cli                        # CLI (build-client-programs is an alias)
make -C installer/operator build      # operator manager binary

3. Run tests (the operator's envtest is the most likely to surface a toolchain issue):

cd client-programs && go test ./...
make -C installer/operator test

Step 4: Post-Verification Checklist

• go.work updated
• All four platform go.mod files updated (client-programs, installer/operator, node-ca-injector, assets-server)
• All five Dockerfiles with FROM ...golang: updated, --platform=$BUILDPLATFORM prefix preserved where present
• CI: no stray hardcoded go-version:/golang:1. literal left (versions come from go-version-file: <module>/go.mod)
• go mod tidy ran cleanly in all modules
• CLI builds (make build-cli) and operator builds + tests (make -C installer/operator build test)
• No remaining references to the old Go version (grep -rn "golang:1\.<old>" --include="Dockerfile*" .)

If go mod tidy changes go.sum, commit that change but confirm with the user first.