go-upgrade

name

go-upgrade

description

Upgrade the Go version used by this project. Follows the procedure in `docs/maintenance/go-upgrade.md` and updates `mise.toml`, runs `make sync-versions` to propagate the new version to `go.mod` and the relevant Dockerfile / README files, then rebuilds dependencies, tooling, and generated code and verifies with tests and lint. The target version is confirmed with the user at execution time, and the skill also offers an optional Go module dependency update (latest minor / patch-only / skip) as part of the same upgrade.

Go Version Upgrade Procedure

This skill defines the work procedure for upgrading the Go version used by this project to an arbitrary target version.

The canonical procedure document is:

• docs/maintenance/go-upgrade.md

A Japanese reference translation of this skill is available at SKILL.ja.md in the same directory (not loaded as a skill; for human reference only).

First Step: Confirm the Target Version

This skill MUST call AskUserQuestion immediately after invocation to confirm the target version. Even if a version-like string is present in the skill arguments or the most recent user message, do NOT adopt it silently and proceed (an explicit confirmation is required to prevent misconfiguration).

Procedure:

1. Read the go = "X.Y.Z" entry under [tools] in mise.toml to determine the current version.
2. Always invoke AskUserQuestion to ask the user:
   • Question: "Specify the target Go version to upgrade to (e.g., 1.26.3)."
   • Include the current version (the value of [tools] go in mise.toml) as additional context.
   • If a version candidate is found in the skill arguments or recent message, include it in the question as "Candidate: X.Y.Z" and let the user confirm.
3. Validate that the answer is in X.Y.Z format. Use it as <TARGET_VERSION> throughout the rest of the procedure.

Do NOT modify any files or execute any commands until the target version has been confirmed.

Preconditions

• Target version: <TARGET_VERSION> (the value confirmed above)
• Do NOT work directly on the production / develop / staging / release/* branches (see Git rules in AGENTS.md).
• Create a working branch from the latest release/* (e.g., feature/go-upgrade-<TARGET_VERSION>).

AI Modification Scope

Per the "Exception: Skill Execution" clause in AGENTS.md, the normal AI Modification Scope restrictions are relaxed for the duration of this skill's execution. The following paths are permitted to be modified while this skill is running:

• mise.toml (the go entry under [tools])
• go.mod, go.sum, vendor/ (regenerated by make tidy-lib)
• docker/**/Dockerfile (automatically rewritten by make sync-versions, and the FROM @sha256:... digest by make pin-images-apply)
• docker/**/README.md / README.ja.md (automatically rewritten by make sync-versions)
• docker/images-pin.toml (the base-image digest lockfile, rewritten by make pin-images-resolve)

The following remain protected even during skill execution:

• AGENTS.md / CLAUDE.md
• Generated files (**/*.gen.go, *.sql.go, *_mock.go, **/openapi.gen.yaml, generated content under docs/)

Execution Steps

Perform the following, mirroring the steps in docs/maintenance/go-upgrade.md. Replace every occurrence of <TARGET_VERSION> in commands and file contents with the version confirmed by the user.

1. Check the Release Notes

Check the release notes for <TARGET_VERSION> at https://go.dev/doc/devel/release.

Items to review:

• Language spec changes
• Breaking changes in the standard library
• Behavior changes in go vet
• Toolchain changes

2. Update mise.toml

Edit mise.toml and set the go entry under [tools]:

[tools]
go = "<TARGET_VERSION>"
# (other entries unchanged)

mise.toml is the single source of truth for the Go runtime version (and for all other tool versions). All downstream files are regenerated from it by the next step.

3. Propagate the New Version with make sync-versions

make sync-versions

This runs scripts/sync-versions (Go) and rewrites the following files in lockstep:

• go.mod — the go X.Y.Z directive
• docker/server/Dockerfile — FROM golang:X.Y.Z-alpine lines
• docker/tools/Dockerfile — FROM golang:X.Y.Z-alpine (and FROM node: / FROM python: for the other runtimes)
• docker/README.md / docker/README.ja.md — golang:X.Y.Z-alpine table cells
• docker/server/README.md / docker/server/README.ja.md — same
• docker/tools/README.md / docker/tools/README.ja.md — same

The skill MUST run this command itself after editing mise.toml. Manual edits to go.mod / Dockerfile / README files are not required.

4. Update the Local Go Environment

make go-update

Internally runs mise install go, which reads the go entry from mise.toml. Verify:

go version

The local environment update is a user task. The AI agent must NOT run mise install itself; instead, ask the user to perform this step (and confirm go version matches <TARGET_VERSION>).

5. Update Dependencies and Vendor

make tidy-lib

(Internally runs go mod tidy and go mod vendor.)

5.5. (Optional) Update Go Module Dependencies

A Go runtime upgrade is a natural point to also refresh the module dependencies. Ask the user whether to update, then act on the answer.

This step MUST call AskUserQuestion to confirm the update level. Offer:

• Latest minor (go get -u ./...) — update all direct/indirect deps to the latest minor/patch within the same major. Picks up new features; small risk of behavior changes.
• Patch only (go get -u=patch ./...) — stay within the current minor; safest.
• Skip — leave dependencies untouched (Go directive bump only).

Never bump a major version automatically (go get -u stays within the current major by design); major upgrades are a separate, deliberate task.

If the user chooses to update:

go get -u ./...        # or: go get -u=patch ./...
make tidy-lib          # re-run go mod tidy + go mod vendor

After running, review the go.mod diff: the go directive must remain at <TARGET_VERSION> and no unintended toolchain line should be added by a dependency. The subsequent rebuild / gen / test / lint steps then verify the runtime bump and the dependency update together.

Note: this repository has a thick test + lint suite (including real-DB infrastructure tests), so a green run gives high confidence for minor/patch updates — but it is not a guarantee. For runtime-sensitive core deps (DB driver, OpenTelemetry, web framework), skim their CHANGELOG even when green.

6. Reinstall Go Tools

make install-tools

7. Confirm CI Auto-detection

GitHub Actions workflows under .github/workflows use actions/setup-go with go-version-file: go.mod. Because step 3 already rewrote go.mod, the workflows pick up <TARGET_VERSION> automatically. No manual workflow edit is required.

If a workflow file hard-codes a Go version somewhere (string literal), align it to <TARGET_VERSION> manually.

8. Confirm Dockerfile / README Sync

Step 3 already rewrote the Dockerfile FROM tags and the docker/**/README.md image references. No manual edit is required.

8.5. Refresh Base Image Digest Pins

Step 3 changed the FROM golang: tag, but the previously-pinned @sha256:... digest still points at the OLD Go image — a tag/digest mismatch (Docker honors the digest, so a build would silently pull the old image). Re-pin from the registry so the digest tracks the new tag. This is the pin-images skill's job (chained here per its sibling relationship):

make pin-images-resolve   # run `docker login` first if Docker Hub returns 429
make pin-images-apply
make pin-images-check

The new Go image was just published, so it is normally inside the PIN_IMAGES_MIN_AGE_DAYS cooldown (default 14 days) and gets quarantined: pin-images-apply strips the now-stale digest and leaves the FROM on the tag only, which pin-images-check accepts. Report this to the user and note that /pin-images should be re-run once the new image ages past the window to restore the digest pin. See the pin-images skill for detail.

9. Rebuild Docker Containers

Because the Go base image tag changes with this upgrade, use the clean (--no-cache --pull) variants so the new image is actually pulled and rebuilt:

make serve-build-clean
make tool-runners-build-clean

10. Re-run Code Generation

make gen

11. Run Tests

make test

12. Run Lint

make lint

13. Final Verification

Confirm all of the following commands succeed:

make sync-versions
make pin-images-check
make tidy-lib
make install-tools
make gen
make test
make lint
make serve-build-clean
make tool-runners-build-clean

make sync-versions is included so that any leftover drift between mise.toml and downstream files is caught before the work is reported as done.

Checklist

Confirm the following before reporting completion:

• Target version <TARGET_VERSION> confirmed with the user via AskUserQuestion
• Release notes reviewed
• mise.toml [tools] go updated to <TARGET_VERSION>
• make sync-versions executed (propagates to go.mod / Dockerfile / docker/**/README.md)
• Base image digests re-pinned (make pin-images-resolve + pin-images-apply + pin-images-check); new Go image quarantined-until-aged is reported for a later /pin-images re-run
• Local Go updated via make go-update (user task)
• make tidy-lib executed
• (Optional) Go module dependency update confirmed with the user via AskUserQuestion; if chosen, executed (go get -u[=patch] ./... + make tidy-lib) with the go directive left at <TARGET_VERSION>
• make install-tools executed
• Docker containers rebuilt
• Code generation re-run
• Tests run
• Lint run

Notes

• Do NOT manually edit go.mod / Dockerfile / docker/**/README.md — make sync-versions owns those files. Edit mise.toml and re-run sync.
• Do NOT manually edit generated code (**/*.gen.go, *.sql.go, *_mock.go, etc.).
• Commit on the working branch. Direct commits to production / develop / staging / release/* are prohibited.
• Push to a PR only when the user has explicitly instructed you to do so.
• After updating SKILL.md, also update SKILL.ja.md to keep the Japanese translation in sync.