Update Go version across the Pyroscope codebase (go.mod, go.work, CI workflows, Dockerfiles, goreleaser, examples). Use when bumping Go to a new patch or minor version.
Updates the Go version across all relevant files in the Pyroscope codebase.
/update-go-version 1.25.7
If no version argument is provided, do NOT guess. Instead:
curl -s 'https://go.dev/dl/?mode=json' | jq -r '.[].version'Version validation: The target version MUST be a full patch version (e.g. 1.25.7), not just a minor version (e.g. 1.25 or 1.25.0). If the user provides X.Y.0 or X.Y, warn them that they should use the latest patch release for that minor (check go.dev for the latest). Using .0 means missing security patches and will cause the toolchain directive to be dropped from go.mod files (Go removes it when it equals the directive).
goAlways create a new branch from the latest main before making any changes. Never commit directly to main.
git checkout main
git fetch origin
git pull origin main
git checkout -b update-go-X.Y.Z
Use the naming convention update-go-X.Y.Z where X.Y.Z is the target version.
Extract the current versions from the codebase:
go directive from go.mod (line 3, e.g. go 1.24.6)toolchain directive from go.mod (line 5, e.g. toolchain go1.24.9)go-version from .github/workflows/ci.yml (e.g. 1.24.13)Report these to the user before making changes.
Compare the target version against the current toolchain directive in go.mod:
toolchain go1.25.3, target 1.25.7): patch bump. Only the toolchain directive and build/CI files need updating.toolchain go1.24.9, target 1.25.7): minor bump. The toolchain directive and build/CI files need updating. Ask the user whether to also update the go directive (see step 4).Tell the user which type was detected before proceeding.
The tools/upgrade-go-version.sh script handles CI, Dockerfile, and release config updates. It also creates a git commit with those changes:
bash tools/upgrade-go-version.sh X.Y.Z
This updates and commits:
.github/workflows/*.yml — go-version: values.goreleaser.yaml — version check hook.pyroscope.yaml — ref: for Go stdlib source linking and GO_VERSIONtools/update_examples.Dockerfile — GO_VERSION ARGFROM golang: base image tag (excluding ebpf testdata)toolchain directive in go.mod and go.work filesUpdate the toolchain directive to goX.Y.Z in all go.mod files using go mod edit, and the root go.work using go work edit:
# For go.mod files:
go mod edit -toolchain=goX.Y.Z <file>
# For go.work files (go mod edit does NOT work on .work files):
go work edit -toolchain=goX.Y.Z <file>
go.mod files:
go.modapi/go.modlidia/go.modexamples/golang-pgo/go.modexamples/tracing/golang-push/go.modexamples/language-sdk-instrumentation/golang-push/rideshare/go.modexamples/language-sdk-instrumentation/golang-push/rideshare-alloy/go.modexamples/language-sdk-instrumentation/golang-push/rideshare-k6/go.modexamples/language-sdk-instrumentation/golang-push/simple/go.modgo.work (root only — use go work edit):
go.workgo directive (minor bump only)The go directive sets the minimum compatible Go version. Only update it when:
If updating the go directive, the go and toolchain values MUST differ to prevent Go from dropping the toolchain line. Use two separate calls:
# For go.mod files:
go mod edit -go=X.Y.0 <file>
go mod edit -toolchain=goX.Y.Z <file>
# For go.work files (go mod edit does NOT work on .work files):
go work edit -go=X.Y.0 <file>
go work edit -toolchain=goX.Y.Z <file>
Also update the go directive in all go.work files (use go work edit):
go.workexamples/golang-pgo/go.workexamples/tracing/golang-push/go.workexamples/language-sdk-instrumentation/golang-push/rideshare/go.workexamples/language-sdk-instrumentation/golang-push/rideshare-alloy/go.workexamples/language-sdk-instrumentation/golang-push/rideshare-k6/go.workexamples/language-sdk-instrumentation/golang-push/simple/go.workmake go/mod
This runs go work sync and go mod tidy across all modules. Required because CI runs check/go/mod.
Review the diff. Expected: go.sum changes, small indirect dependency bumps. Investigate anything unexpected.
make go/bin
If the build fails, investigate and fix before proceeding.
The script already committed CI/Dockerfile/release changes. Now commit the go.mod/go.work/go.sum changes:
git add -u *.mod *.sum *.work api/ lidia/ examples/
Use a commit message that reflects what changed:
"Update Go toolchain to goX.Y.Z""Update Go to X.Y.Z (go directive + toolchain)"Show the user:
| Directive | Meaning | When to update |
|---|---|---|
go X.Y.Z | Minimum Go version for compatibility | Only when a dependency or language feature requires it |
toolchain goX.Y.Z | Exact build version (bug fixes, security) | Every bump (patch and minor) |
CI go-version | Exact version CI uses to build/test | Every bump (via script) |
Dockerfile golang:X.Y.Z | Exact version for container builds | Every bump (via script) |