Grafana Loki 发布准备Prepare Release流程全解析基于 release-please 的自动化发布 PR 管线【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki本篇指南以 Grafana Loki 仓库的 prepare-release.md 文档为主体结合仓库内.github/release-workflows.jsonnet、.github/workflows/下的真实工作流文件与 Makefile 相关目标深入讲解 Loki 如何用 release-please 自动维护长期运行的发布 PR、按分支自动区分补丁版/次版本/主版本发布以及如何为罕见的主版本发布手工生成定制工作流。读完本文你将掌握 Loki 发布准备管线的完整链路、分支命名与版本策略的对应关系并能在自己的仓库中复刻这套自动化发布体系。一、发布准备管线是什么在 Grafana Loki 中发布一个版本本质上就是合并一个长期运行的发布 PRlong-running release PR。这个 PR 不是人工临时创建的一次性分支而是由两条 GitHub Actions 工作流持续维护的活 PR——每当目标分支有新提交工作流就会自动重新运行把最新的提交、版本号、变更日志和构建产物刷新进同一个 PR 中。这两个工作流的触发条件在仓库的.github/release-workflows.jsonnet中定义.github/release-workflows.jsonnet工作流生成的文件触发分支模式版本策略适用场景补丁版Patch.github/workflows/patch-release-pr.ymlrelease-[0-9].[0-9].xalways-bump-patch维护分支上的 bug 修复如release-3.4.x次版本Minor.github/workflows/minor-release-pr.ymlk[0-9]always-bump-minor每周发布分支weekly branch如k299正式发布.github/workflows/release.ymlrelease-[0-9].[0-9].x、k[0-9]、main——合并发布 PR 后真正打出 Release从源码结构可以推断release-[0-9].[0-9].x是补丁维护分支的命名约定而k[0-9]是 Loki 按周切出的周分支命名约定两者分别对应 patch 与 minor 两条发布路径。这条管线每一步做的事情即文档列出的四项核心工作会在下文逐一展开。二、管线执行的四个核心步骤无论补丁版还是次版本这套 release-please 驱动的管线都会按顺序完成以下四件事运行测试与静态检查Run tests and linting工作流会先调用check任务复用grafana/loki-release仓库中按固定 SHA 引用的检查工作流注入build_image、golang_ci_lint_version等参数确保待发布的提交质量过关。为拟发布版本构建二进制与镜像Build binaries and images对dist、loki、logcli、loki-canary、fluentd、fluent-bit、logstash、querytee、loki-docker-driver、loki-helm-test等一系列目标执行构建产出跨平台产物。基于 Conventional Commits 生成发布说明Generate release notesrelease-please 扫描自上次发布以来的提交依据约定式提交规范自动归类生成 CHANGELOG。创建或更新长期发布的发布 PRCreate or update the long-running release PRPR 中会明确如果合并将发布哪个 commit并附上已构建产物artifacts的链接。第 3 步依赖的约定式提交规范在仓库中有配套的强制检查.github/workflows/conventional-commits.yml 会在每个 PR 上通过action-semantic-pull-request校验标题格式并要求标题正文以大写字母开头。这意味着 release-please 能够准确从提交历史中提取 feature / fix / chore 等分类是自动生成高质量发布说明的前提。三、从 jsonnet 到工作流配置源头与生成命令Loki 的发布工作流并非手写 YAML而是由 Jsonnet 模板声明式生成。所有发布相关工作流的单一事实来源是 .github/release-workflows.jsonnet其中通过lokiRelease.releasePRWorkflow(...)这个从grafana/loki-release库导入的工厂函数生成补丁版、次版本与正式发布三条工作流。关键的公共参数包括branches工作流监听的分支正则buildImage构建用的 Go 镜像如golang:1.26.6golangCiLintVersiongolangci-lint 版本当前为v2.10.1imageBuildTimeoutMin镜像构建超时60 分钟imageJobs要构建的镜像清单覆盖 loki、logcli、loki-canary、fluentd、fluent-bit、logstash、querytee、loki-docker-driver、loki-helm-test 等并分别指定 amd64/arm64/arm 平台矩阵imagePrefix镜像推送前缀us-docker.pkg.dev/grafanalabs-global/dockerhub-loki-prod-mirrorreleaseLibRefgrafana/loki-release依赖库的固定 commit SHA保证管线可复现versioningStrategy补丁版为always-bump-patch次版本为always-bump-minor。生成与校验命令修改.github/release-workflows.jsonnet后需要运行 Makefile 中的目标重新生成 YAMLMakefile# 生成全部 release 工作流到 .github/workflows/ make release-workflows # 校验生成结果是否与仓库当前内容一致CI 中常用 make release-workflows-checkmake release-workflows内部执行两条命令先用jb update更新 Jsonnet 依赖再用jsonnet -SJ .github/vendor -m .github/workflows -V GO_VERSION$(GO_VERSION) .github/release-workflows.jsonnet把 Jsonnet 模板渲染为-m指定的输出目录下的多个 YAML 文件。release-workflows-check则会重新生成并用git diff --exit-code检查差异若不一致会提示Please build release workflows by running make release-workflows。此外Makefile 还提供了 update-loki-release-sha 目标用于自动把grafana/loki-release依赖更新到最新 commit 并重新生成工作流保证 release 库的修复能够流入发布管线。四、release-please 的调用细节PR 如何被创建与更新以次版本工作流 .github/workflows/minor-release-pr.yml 为例其create-release-pr任务在dist等构建任务全部成功之后才运行核心是一条release-please release-pr命令。值得注意的关键参数yarn exec -- release-please release-pr \ --changelog-path CHANGELOG.md \ --consider-all-branches \ --group-pull-request-title-pattern chore${scope}: Release${component} ${version} \ --label backport main,autorelease: pending,product-approved \ --manifest-file .release-please-manifest.json \ --pull-request-footer Merging this PR will release the artifacts of ${SHA} \ --release-as $(version) \ --release-type simple \ --target-branch $(branch) \ --token $(github app token) \ --dry-run false--consider-all-branches--target-branch让 release-please 在所有分支上独立计算版本并精确操作当前触发分支--label给发布 PR 自动打上backport main、autorelease: pending、product-approved标签其中backport main意味着合入后会自动回移植到 main 分支--pull-request-footer把 PR 尾注写成合并此 PR 将发布某 commit 的 artifacts 链接正是文档所述指示将被发布的 commit 并附带构建产物链接的落地实现--release-as由version任务计算出的拟发布版本号直接指定命令使用 GitHub Apploki-gh-app签发的 token 而不是普通 GITHUB_TOKEN以便绕过仓库对机器人提交的 CI 限制。从工作流依赖图可以看出create-release-pr依赖dist、fluent-bit、fluentd、logcli、logstash、loki、loki-canary、loki-canary-boringcrypto、loki-docker-driver、loki-helm-test、querytee等全部构建任务——即先构建产物、再开 PR确保 PR 中的产物链接始终有效。五、构建产物如何产生与存储构建阶段的实际动作在dist任务中完成.github/workflows/patch-release-pr.ymlcheckout 待发布仓库与 release 库在golang:1.26.6容器内执行make dist packages产出二进制包另有一个continue-on-error: true的可选步骤构建dist/loki-linux-riscv64即 riscv64 这类非主流架构构建失败不会阻塞整个发布使用gcloud artifacts generic upload把dist/上传到 Google Artifact RegistryGAR的generic-loki-dev仓库--packagebinaries、--version${{ github.sha }}即以 commit SHA 作为产物版本标识。各镜像任务loki、logcli、loki-canary 等则用docker/build-push-action按linux/amd64、linux/arm64、linux/arm平台矩阵分别构建并导出为 tar再以--packageimages上传loki-docker-driver以typelocal输出 rootfs 后打包上传到--packageplugins。这样合并发布 PR 后正式发布工作流 .github/workflows/release.yml 就可以按 SHA 从 GAR 下载这些产物直接打 Release而不必在发布时重新构建保证PR 中验证过的产物 最终发布的产物。六、主版本发布手工创建定制工作流主版本Major发布与 minor / patch 走完全相同的流程区别仅在于主版本不常发生没有必要让工作流长期保持运行因此需要为要发布的分支手工创建一条定制工作流。完整步骤记录在 major-release.md 中操作要点如下编辑.github/release-workflows.jsonnet注意文档中的路径写法对应仓库根目录下的 .github/release-workflows.jsonnet添加一条新的主版本发布工作流。以 3.0 发布为例模板代码如下three-zero-release.yml: std.manifestYamlDoc( lokiRelease.releasePRWorkflow( branches[release-3.0.0], buildImagebuildImage, checkTemplatecheckTemplate, golangCiLintVersiongolangCiLintVersion, imageBuildTimeoutMinimageBuildTimeoutMin, imageJobsimageJobs, imagePrefiximagePrefix, releaseLibRefreleaseLibRef, releaseRepografana/loki, skipArmfalse, skipValidationfalse, useGitHubAppTokentrue, releaseAs3.0.0, ) { name: Prepare Loki 3.0 release, }, false, false ),确保branches字段指向你要发布的分支上例为release-3.0.0确保releaseAs字段设置为你想要的版本号上例为3.0.0这是与 patch/minor 工作流最大的区别——主版本必须显式指定而不是依赖递增策略运行make release-workflows生成新的工作流文件并将这次改动同时合并到main 分支和 release 分支建议在同一个 PR 中顺带禁用 patch 发布工作流理由见下一节。与补丁发布工作流的竞态问题新创建的主版本工作流会与 patch 工作流产生竞态race conditionpatch 工作流监听release-[0-9].[0-9].x模式而主版本分支release-3.0.0也匹配该正则两条工作流可能同时尝试更新发布 PR导致版本号计算或 PR 内容相互覆盖。文档给出了两种解法禁用 patch 发布工作流直到主版本发布完成后再恢复人工盯守发布分支上的所有 Actions例如release-3.0.x分支的 runs发现 patch 工作流触发就手动取消。从工程实践看方案一更稳妥也是文档建议作为该 PR 的一部分一并完成的操作。七、合并发布 PR 之后正式发布工作流发布 PR 合入后release.yml工作流.github/workflows/release.yml接管后续动作通过shouldRelease任务判断当前提交是否应该发布然后按github.sha从 GAR 下载二进制检查同名 Release 是否已存在避免重复发布再创建或更新GitHub Release、推送镜像 tag。至此准备prepare→ 合并merge→ 发布publish三段式发布流程闭环完成其中本文介绍的 prepare 阶段正是整个链条的入口。八、在自有仓库复刻这套流程的要点分支即版本策略用稳定的分支命名约定如release-x.y.z模式 递增策略驱动版本管理避免人工维护版本号配置即代码把工作流定义收敛到 Jsonnet / 模板文件用make目标统一生成与校验杜绝手改 YAML 造成的漂移先产物后 PR让发布 PR 的创建依赖全部构建任务PR 内直接附上可验证的产物链接固定依赖引用用 commit SHA 锁定 release 库RELEASE_LIB_REF与构建工具版本保证任何时刻重跑管线结果一致约定式提交是前提release-please 的发布说明质量取决于提交信息规范度务必配套 PR 标题校验参考 .github/workflows/conventional-commits.yml。相关文档与源码索引本文主体文档prepare-release.md主版本发布步骤major-release.md工作流声明模板.github/release-workflows.jsonnet生成的工作流.github/workflows/patch-release-pr.yml、.github/workflows/minor-release-pr.yml、.github/workflows/release.yml生成与校验命令Makefile【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考