Grafana Tempo Go 版本升级实战基于 update-go-version Skill 的跨文件版本同步流程解析【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempo本文以 Grafana Tempo 仓库内置的update-go-versionSkill.claude/skills/update-go-version/SKILL.md为骨架系统讲解如何在 Tempo 代码库中完成一次完整的 Go 工具链版本升级从tools/Dockerfile提取目标版本、同步go.mod与tools/go.mod的go指令、更新build/tools.mk中的 CI 工具镜像 Tag再到用make vendor与make build验证改动。读完本文你将掌握 Tempo 仓库中 Go 版本在各构建环节的分布关系、Renovate 自动更新与人工落地的配合方式以及一套可直接复用的升级操作清单。一、Skill 概览它解决什么问题update-go-version是 Tempo 仓库为 AI 助手Claude定义的一个操作型 Skill其前导元数据frontmatter明确了职责边界name: update-go-version description: Update Go version across the Tempo codebase (go.mod, tools/go.mod, Dockerfile, CI workflows, tools image tag) allowed-tools: WebFetch, Grep, Read, Write从描述可以看出它的核心任务不是改一个文件而是跨文件同步Go 版本在 Tempo 仓库中并非只存在于一处而是散落在主模块go.mod、工具模块tools/go.mod、CI 工具镜像tools/Dockerfile以及构建脚本build/tools.mk等多个位置任何一处遗漏都会导致版本漂移。该 Skill 通过/update-go-version命令被调用执行路径包含 5 个明确的步骤见下文第三节。二、为什么 Go 版本需要多点同步版本分布全景先看当前仓库中 Go 版本的实际分布这决定了升级操作必须覆盖哪些文件。1. 主模块与工具模块的go指令Tempo 采用 Go 模块化组织存在两个独立的 Go module主模块 go.mod 第 3 行声明go 1.26.5承载cmd/tempo、modules/*、tempodb、pkg/*等全部核心代码工具模块 tools/go.mod 第 3 行同样声明go 1.26.5但它不产生业务二进制而是通过 Go 1.24 的tool指令统一管理开发期工具链tool ( github.com/golangci/golangci-lint/v2/cmd/golangci-lint github.com/google/go-jsonnet/cmd/jsonnet github.com/google/go-jsonnet/cmd/jsonnetfmt github.com/psampaz/go-mod-outdated golang.org/x/tools/cmd/goimports golang.org/x/tools/cmd/goyacc gotest.tools/gotestsum mvdan.cc/gofumpt )这些工具通过 tools/install.sh 中的go install tool一次性安装脚本注释明确指出这是 Go 1.24 的 tool directive 机制。2. CI 工具镜像的 Go 基础镜像tools/Dockerfile 是 CI 工具镜像grafana/tempo-ci-tools的构建定义其第一行即固定了 Go 工具链版本FROM golang:1.27.1-alpinesha256:cf6fca6641884b8433441b2b0652976f975e1d0fdd26d177eaaf8596087f3125该镜像内部还会安装buf、protoc-gen-gogofaster、wiresmith、tk、jb等构建期工具并以/tools/install.sh安装 tools 模块中声明的全部 tool。注意当前仓库中tools/Dockerfile的 Go 版本1.27.1已经领先于两个go.mod的go 1.26.5——这正是 Skill 所描述的典型场景Renovate 自动把镜像基础版本推高随后需要人工把go.mod的指令同步上去。3. 构建脚本中的工具镜像 Tagbuild/tools.mk 中定义了工具镜像及其 TagTOOLS_IMAGE ? grafana/tempo-ci-tools TOOLS_IMAGE_TAG ? main-3f54f1c-20260716-212549Tag 格式为main-XXXXXXX分支名 7 位短 SHA 日期时间其生成逻辑见 tools/image-tag脚本用git rev-parse --short7 HEAD取短 SHA再拼上分支名形成类似main-3f54f1c-20260716-212549的标识。TOOLS_IMAGE_TAG被用于TOOLS_CMD运行 lint 等工具和LINT_CMD两条 docker run 命令以及tools-image目标的docker pull。4. CI 工作流中的版本引用Tempo 的 GitHub Actions 工作流并不硬编码 Go 版本而是通过go-version-file引用上述模块文件从而让版本变更自动传导到 CI.github/workflows/ci.yml 中的 lint、构建、测试等多个 job 均使用go-version-file: go.mod.github/workflows/tools-tests.yml 针对工具模块使用go-version-file: tools/go.modchangelog.yml、release-prep.yml、govulncheck.yml等同样引用go.mod或tools/go.mod。因此只要两个go.mod同步到位CI 就会自动使用新版本编译无需逐一手改 workflow。三、升级流程分步详解Skill 核心步骤Step 1从 tools/Dockerfile 获取目标版本升级的权威版本源是tools/Dockerfile——该文件由 Renovate 工作流自动更新见下文第六节因此每次执行升级前先读取其中的FROM golang:X.Y.Z-alpinesha256:...行提取X.Y.Z。例如当前仓库中是1.27.1。这一步之所以以 Dockerfile 为准是因为镜像必须先构建、推送CI 才能拉到带新工具链的镜像go.mod的指令如果超前于镜像中的工具链编译验证将无法进行。Step 2检查两个 go.mod 是否已匹配提前终止条件检查以下两个文件中的go指令go.mod主模块tools/go.mod工具模块如果两个文件中的版本已经与tools/Dockerfile一致说明版本同步已完成此时 Skill 要求告知用户tools/Dockerfile需要先被更新并合并、以构建新镜像然后停止不要继续执行后续步骤。这是一个重要的幂等保护——避免在镜像尚未就绪时重复改文件或更新 Tag。Step 3更新 go.mod 文件若版本不匹配则将两个文件顶部的go X.Y.Z指令统一改为 Step 1 提取的新版本// go.mod主模块 module github.com/grafana/tempo go 1.27.1// tools/go.mod工具模块 module github.com/grafana/tempo/tools go 1.27.1需要说明的是Tempo 的go指令采用了带补丁号的完整版本如1.26.5而非传统的仅主次版本写法如1.26升级时保持同样的完整版本格式以与本仓库约定一致。Step 4更新 build/tools.mk 中的 TOOLS_IMAGE_TAG用 Docker Hub API 获取grafana/tempo-ci-tools镜像的最新 Tagcurl -s https://hub.docker.com/v2/repositories/grafana/tempo-ci-tools/tags?page_size5orderinglast_updated | jq -r .results[0].name将 build/tools.mk 第 13 行的TOOLS_IMAGE_TAG ? main-XXXXXXX替换为查询到的最新 Tag。这里有一个隐含依赖该 Tag 对应的镜像必须是基于新的tools/Dockerfile即新 Go 版本构建并推送的因此 Step 1 中提到的先合并 Dockerfile 变更、构建镜像是整个链路的前置条件。Step 5验证改动可编译最后在仓库根目录执行make vendor make build从 Makefile 的源码看这两条命令与版本变更的关联如下make vendor的底层是update-mod目标约第 383-386 行先执行tools-update-mod即go mod tidy再执行go mod vendor与go mod tidy -e用于在新工具链下重新整理依赖与 vendor 目录make build依赖tempo目标第 84 行$(GO_ENV) go build $(GO_OPT) -o ./bin/$(GOOS)/tempo-$(GOARCH) $(BUILD_INFO) ./cmd/tempo其中GO_OPT -mod vendor第 55 行强制以 vendor 模式编译确保构建使用的依赖与go.sum、vendor 目录完全一致。此外Makefile 的vendor-check目标第 377-379 行会执行git diff --exit-code -- **/go.sum **/go.mod vendor/ ...用于在 CI 中校验 vendor 与生成文件是否同步可作为升级后自查的命令。四、升级涉及的文件清单Skill 文档末尾给出了完整的影响面清单整理如下文件修改内容go.modgo X.Y.Z指令tools/go.modgo X.Y.Z指令build/tools.mkTOOLS_IMAGE_TAG值对照第二节的版本分布图可以确认该清单的完整性tools/Dockerfile由 Renovate 自动维护不在人工修改清单内CI 工作流通过go-version-file间接引用两个go.mod无需修改因此人工只需改这 3 个文件即可完成全链路同步。五、仓库源码佐证版本同步背后的机制细节1. TOOLS_IMAGE_TAG 的消费路径build/tools.mk 中Tag 的实际消费点有TOOLS_CMD docker run --rm -t -v ${PWD}:/tools $(WORKTREE_DOCKER_MOUNT) $(TOOLS_IMAGE):$(TOOLS_IMAGE_TAG) LINT_CMD docker run --rm -t -v ${PWD}:/tools $(WORKTREE_DOCKER_MOUNT) -v ${PWD}/.cache/golangci-lint:/root/.cache/golangci-lint $(TOOLS_IMAGE):$(TOOLS_IMAGE_TAG)tools-image目标第 37-39 行执行docker pull $(TOOLS_IMAGE):$(TOOLS_IMAGE_TAG)tools-image-build目标第 27-30 行则用docker build -t $(TOOLS_IMAGE) -f ./tools/Dockerfile .在本地构建该镜像。也就是说升级后必须先tools-image-build或等 CI 构建推送新 Tag再更新TOOLS_IMAGE_TAG否则docker pull会拉到旧镜像lint 等工具仍跑在旧 Go 版本上。2. Renovate 的自动更新与人工落地的分工.github/renovate.json5 揭示了自动化的边界第 42-53 行的customManagers用正则同时匹配Makefile与build/tools.mk中的TOOLS_IMAGE_TAG ? main-[0-9a-f]{7}-\d{8}-\d{6}数据源为 Docker也就是说TOOLS_IMAGE_TAG本身也是 Renovate 的自动更新对象第 144-148 行针对go、golang依赖做了 Fast-trackrangeStrategy: bump、minimumReleaseAge: 0 days让 Go 版本更新不等待发布冷却期tools/Dockerfile的golang:1.27.1-alpine同样属于 docker 管理器第 136-142 行将 Docker 更新归组。因此实际工作流是Renovate 先提交tools/Dockerfile与build/tools.mk的更新 PR并构建新镜像→ 人工或 Skill 助手执行 Step 2-3 把两个go.mod的指令补齐。这与 Skill 中若版本已匹配则提示先更新并合并 Dockerfile 再停止的逻辑完全自洽。3. 运行时镜像与 Go 版本的解耦值得注意cmd/tempo/Dockerfile 最终运行时镜像基于gcr.io/distroless/static-debian12Go 程序是静态编译产物CGO_ENABLED0见 Makefile 第 58 行的GO_ENVCGO_ENABLED0因此升级 Go 版本不会影响运行时镜像cmd/tempo/Dockerfile不在升级清单内。六、实操注意事项严格遵守提前终止条件Step 2 检测到两个go.mod已匹配时不要继续更新TOOLS_IMAGE_TAG——新 Tag 可能尚未就绪强行更新会导致docker pull失败或 CI 使用错误镜像。Tag 与镜像的时序依赖TOOLS_IMAGE_TAG必须是已推送的镜像 Tag。升级后应通过tools-imagedocker pull验证 Tag 可拉取再提交build/tools.mk的改动。补丁号格式本仓库go指令采用X.Y.Z完整格式当前为1.26.5不要简写为X.Y。验证命令的完整性make vendor会改动go.mod、go.sum与vendor/目录提交前可用make vendor-check的 diff 检查逻辑自查make build则验证主模块能在新工具链下以 vendor 模式编译通过。只读环境约束仓库为只读执行升级属于本地开发流程本文描述的改动仅针对你本地检出的代码副本不涉及修改远程仓库。七、升级核对清单完成一次 Go 版本升级后建议逐项核对已从 tools/Dockerfile 提取新版本号X.Y.Zgo.mod 的go指令已更新tools/go.mod 的go指令已更新build/tools.mk 的TOOLS_IMAGE_TAG已指向基于新镜像构建的 Tag新 Tag 对应的镜像已构建并推送或可通过docker pull拉取make vendor与make build均通过CI 工作流.github/workflows/ci.yml、.github/workflows/tools-tests.yml无需改动已通过go-version-file自动跟随新版本【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Grafana Tempo Go 版本升级实战：基于 update-go-version Skill 的跨文件版本同步流程解析
Grafana Tempo Go 版本升级实战基于 update-go-version Skill 的跨文件版本同步流程解析【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempo本文以 Grafana Tempo 仓库内置的update-go-versionSkill.claude/skills/update-go-version/SKILL.md为骨架系统讲解如何在 Tempo 代码库中完成一次完整的 Go 工具链版本升级从tools/Dockerfile提取目标版本、同步go.mod与tools/go.mod的go指令、更新build/tools.mk中的 CI 工具镜像 Tag再到用make vendor与make build验证改动。读完本文你将掌握 Tempo 仓库中 Go 版本在各构建环节的分布关系、Renovate 自动更新与人工落地的配合方式以及一套可直接复用的升级操作清单。一、Skill 概览它解决什么问题update-go-version是 Tempo 仓库为 AI 助手Claude定义的一个操作型 Skill其前导元数据frontmatter明确了职责边界name: update-go-version description: Update Go version across the Tempo codebase (go.mod, tools/go.mod, Dockerfile, CI workflows, tools image tag) allowed-tools: WebFetch, Grep, Read, Write从描述可以看出它的核心任务不是改一个文件而是跨文件同步Go 版本在 Tempo 仓库中并非只存在于一处而是散落在主模块go.mod、工具模块tools/go.mod、CI 工具镜像tools/Dockerfile以及构建脚本build/tools.mk等多个位置任何一处遗漏都会导致版本漂移。该 Skill 通过/update-go-version命令被调用执行路径包含 5 个明确的步骤见下文第三节。二、为什么 Go 版本需要多点同步版本分布全景先看当前仓库中 Go 版本的实际分布这决定了升级操作必须覆盖哪些文件。1. 主模块与工具模块的go指令Tempo 采用 Go 模块化组织存在两个独立的 Go module主模块 go.mod 第 3 行声明go 1.26.5承载cmd/tempo、modules/*、tempodb、pkg/*等全部核心代码工具模块 tools/go.mod 第 3 行同样声明go 1.26.5但它不产生业务二进制而是通过 Go 1.24 的tool指令统一管理开发期工具链tool ( github.com/golangci/golangci-lint/v2/cmd/golangci-lint github.com/google/go-jsonnet/cmd/jsonnet github.com/google/go-jsonnet/cmd/jsonnetfmt github.com/psampaz/go-mod-outdated golang.org/x/tools/cmd/goimports golang.org/x/tools/cmd/goyacc gotest.tools/gotestsum mvdan.cc/gofumpt )这些工具通过 tools/install.sh 中的go install tool一次性安装脚本注释明确指出这是 Go 1.24 的 tool directive 机制。2. CI 工具镜像的 Go 基础镜像tools/Dockerfile 是 CI 工具镜像grafana/tempo-ci-tools的构建定义其第一行即固定了 Go 工具链版本FROM golang:1.27.1-alpinesha256:cf6fca6641884b8433441b2b0652976f975e1d0fdd26d177eaaf8596087f3125该镜像内部还会安装buf、protoc-gen-gogofaster、wiresmith、tk、jb等构建期工具并以/tools/install.sh安装 tools 模块中声明的全部 tool。注意当前仓库中tools/Dockerfile的 Go 版本1.27.1已经领先于两个go.mod的go 1.26.5——这正是 Skill 所描述的典型场景Renovate 自动把镜像基础版本推高随后需要人工把go.mod的指令同步上去。3. 构建脚本中的工具镜像 Tagbuild/tools.mk 中定义了工具镜像及其 TagTOOLS_IMAGE ? grafana/tempo-ci-tools TOOLS_IMAGE_TAG ? main-3f54f1c-20260716-212549Tag 格式为main-XXXXXXX分支名 7 位短 SHA 日期时间其生成逻辑见 tools/image-tag脚本用git rev-parse --short7 HEAD取短 SHA再拼上分支名形成类似main-3f54f1c-20260716-212549的标识。TOOLS_IMAGE_TAG被用于TOOLS_CMD运行 lint 等工具和LINT_CMD两条 docker run 命令以及tools-image目标的docker pull。4. CI 工作流中的版本引用Tempo 的 GitHub Actions 工作流并不硬编码 Go 版本而是通过go-version-file引用上述模块文件从而让版本变更自动传导到 CI.github/workflows/ci.yml 中的 lint、构建、测试等多个 job 均使用go-version-file: go.mod.github/workflows/tools-tests.yml 针对工具模块使用go-version-file: tools/go.modchangelog.yml、release-prep.yml、govulncheck.yml等同样引用go.mod或tools/go.mod。因此只要两个go.mod同步到位CI 就会自动使用新版本编译无需逐一手改 workflow。三、升级流程分步详解Skill 核心步骤Step 1从 tools/Dockerfile 获取目标版本升级的权威版本源是tools/Dockerfile——该文件由 Renovate 工作流自动更新见下文第六节因此每次执行升级前先读取其中的FROM golang:X.Y.Z-alpinesha256:...行提取X.Y.Z。例如当前仓库中是1.27.1。这一步之所以以 Dockerfile 为准是因为镜像必须先构建、推送CI 才能拉到带新工具链的镜像go.mod的指令如果超前于镜像中的工具链编译验证将无法进行。Step 2检查两个 go.mod 是否已匹配提前终止条件检查以下两个文件中的go指令go.mod主模块tools/go.mod工具模块如果两个文件中的版本已经与tools/Dockerfile一致说明版本同步已完成此时 Skill 要求告知用户tools/Dockerfile需要先被更新并合并、以构建新镜像然后停止不要继续执行后续步骤。这是一个重要的幂等保护——避免在镜像尚未就绪时重复改文件或更新 Tag。Step 3更新 go.mod 文件若版本不匹配则将两个文件顶部的go X.Y.Z指令统一改为 Step 1 提取的新版本// go.mod主模块 module github.com/grafana/tempo go 1.27.1// tools/go.mod工具模块 module github.com/grafana/tempo/tools go 1.27.1需要说明的是Tempo 的go指令采用了带补丁号的完整版本如1.26.5而非传统的仅主次版本写法如1.26升级时保持同样的完整版本格式以与本仓库约定一致。Step 4更新 build/tools.mk 中的 TOOLS_IMAGE_TAG用 Docker Hub API 获取grafana/tempo-ci-tools镜像的最新 Tagcurl -s https://hub.docker.com/v2/repositories/grafana/tempo-ci-tools/tags?page_size5orderinglast_updated | jq -r .results[0].name将 build/tools.mk 第 13 行的TOOLS_IMAGE_TAG ? main-XXXXXXX替换为查询到的最新 Tag。这里有一个隐含依赖该 Tag 对应的镜像必须是基于新的tools/Dockerfile即新 Go 版本构建并推送的因此 Step 1 中提到的先合并 Dockerfile 变更、构建镜像是整个链路的前置条件。Step 5验证改动可编译最后在仓库根目录执行make vendor make build从 Makefile 的源码看这两条命令与版本变更的关联如下make vendor的底层是update-mod目标约第 383-386 行先执行tools-update-mod即go mod tidy再执行go mod vendor与go mod tidy -e用于在新工具链下重新整理依赖与 vendor 目录make build依赖tempo目标第 84 行$(GO_ENV) go build $(GO_OPT) -o ./bin/$(GOOS)/tempo-$(GOARCH) $(BUILD_INFO) ./cmd/tempo其中GO_OPT -mod vendor第 55 行强制以 vendor 模式编译确保构建使用的依赖与go.sum、vendor 目录完全一致。此外Makefile 的vendor-check目标第 377-379 行会执行git diff --exit-code -- **/go.sum **/go.mod vendor/ ...用于在 CI 中校验 vendor 与生成文件是否同步可作为升级后自查的命令。四、升级涉及的文件清单Skill 文档末尾给出了完整的影响面清单整理如下文件修改内容go.modgo X.Y.Z指令tools/go.modgo X.Y.Z指令build/tools.mkTOOLS_IMAGE_TAG值对照第二节的版本分布图可以确认该清单的完整性tools/Dockerfile由 Renovate 自动维护不在人工修改清单内CI 工作流通过go-version-file间接引用两个go.mod无需修改因此人工只需改这 3 个文件即可完成全链路同步。五、仓库源码佐证版本同步背后的机制细节1. TOOLS_IMAGE_TAG 的消费路径build/tools.mk 中Tag 的实际消费点有TOOLS_CMD docker run --rm -t -v ${PWD}:/tools $(WORKTREE_DOCKER_MOUNT) $(TOOLS_IMAGE):$(TOOLS_IMAGE_TAG) LINT_CMD docker run --rm -t -v ${PWD}:/tools $(WORKTREE_DOCKER_MOUNT) -v ${PWD}/.cache/golangci-lint:/root/.cache/golangci-lint $(TOOLS_IMAGE):$(TOOLS_IMAGE_TAG)tools-image目标第 37-39 行执行docker pull $(TOOLS_IMAGE):$(TOOLS_IMAGE_TAG)tools-image-build目标第 27-30 行则用docker build -t $(TOOLS_IMAGE) -f ./tools/Dockerfile .在本地构建该镜像。也就是说升级后必须先tools-image-build或等 CI 构建推送新 Tag再更新TOOLS_IMAGE_TAG否则docker pull会拉到旧镜像lint 等工具仍跑在旧 Go 版本上。2. Renovate 的自动更新与人工落地的分工.github/renovate.json5 揭示了自动化的边界第 42-53 行的customManagers用正则同时匹配Makefile与build/tools.mk中的TOOLS_IMAGE_TAG ? main-[0-9a-f]{7}-\d{8}-\d{6}数据源为 Docker也就是说TOOLS_IMAGE_TAG本身也是 Renovate 的自动更新对象第 144-148 行针对go、golang依赖做了 Fast-trackrangeStrategy: bump、minimumReleaseAge: 0 days让 Go 版本更新不等待发布冷却期tools/Dockerfile的golang:1.27.1-alpine同样属于 docker 管理器第 136-142 行将 Docker 更新归组。因此实际工作流是Renovate 先提交tools/Dockerfile与build/tools.mk的更新 PR并构建新镜像→ 人工或 Skill 助手执行 Step 2-3 把两个go.mod的指令补齐。这与 Skill 中若版本已匹配则提示先更新并合并 Dockerfile 再停止的逻辑完全自洽。3. 运行时镜像与 Go 版本的解耦值得注意cmd/tempo/Dockerfile 最终运行时镜像基于gcr.io/distroless/static-debian12Go 程序是静态编译产物CGO_ENABLED0见 Makefile 第 58 行的GO_ENVCGO_ENABLED0因此升级 Go 版本不会影响运行时镜像cmd/tempo/Dockerfile不在升级清单内。六、实操注意事项严格遵守提前终止条件Step 2 检测到两个go.mod已匹配时不要继续更新TOOLS_IMAGE_TAG——新 Tag 可能尚未就绪强行更新会导致docker pull失败或 CI 使用错误镜像。Tag 与镜像的时序依赖TOOLS_IMAGE_TAG必须是已推送的镜像 Tag。升级后应通过tools-imagedocker pull验证 Tag 可拉取再提交build/tools.mk的改动。补丁号格式本仓库go指令采用X.Y.Z完整格式当前为1.26.5不要简写为X.Y。验证命令的完整性make vendor会改动go.mod、go.sum与vendor/目录提交前可用make vendor-check的 diff 检查逻辑自查make build则验证主模块能在新工具链下以 vendor 模式编译通过。只读环境约束仓库为只读执行升级属于本地开发流程本文描述的改动仅针对你本地检出的代码副本不涉及修改远程仓库。七、升级核对清单完成一次 Go 版本升级后建议逐项核对已从 tools/Dockerfile 提取新版本号X.Y.Zgo.mod 的go指令已更新tools/go.mod 的go指令已更新build/tools.mk 的TOOLS_IMAGE_TAG已指向基于新镜像构建的 Tag新 Tag 对应的镜像已构建并推送或可通过docker pull拉取make vendor与make build均通过CI 工作流.github/workflows/ci.yml、.github/workflows/tools-tests.yml无需改动已通过go-version-file自动跟随新版本【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考