在 SourceHut Builds 中自动化生成 git-cliff 变更日志（Changelog）的完整指南

在 SourceHut Builds 中自动化生成 git-cliff 变更日志Changelog的完整指南【免费下载链接】git-cliffA highly customizable Changelog Generator that follows Conventional Commit specifications ⛰️项目地址: https://gitcode.com/gh_mirrors/gi/git-cliff导读本文面向使用 SourceHut 托管代码、并希望借助其免费 CI 服务 builds.sr.ht 自动维护变更日志的开发者。你将掌握如何在.build.yml中编排任务让 git-cliff 在 Alpine 容器内基于 Conventional Commits 生成CHANGELOG.md再通过 SSH 密钥认证自动提交并推回仓库同时会深入理解该流程背后 git-cliff 的命令行参数、输出机制与 CI 安全细节让自动化真正可落地、可复现。为什么选择 SourceHut Builds 来运行 git-cliffgit-cliff 是一个高度可定制的变更日志生成器它从 Git 提交历史出发遵循 Conventional Commits 规范并通过正则驱动的自定义解析器commit_parsers对提交进行分类最终套用可配置的模板生成 changelog。相关能力可以参阅仓库根目录的 cliff.toml 与 config/cliff.toml 中的默认配置以及 website/docs/configuration/git.md 对解析器的说明。将这一流程放到 CI 中有三个直接收益自动化每次合并提交后自动更新CHANGELOG.md无需开发者手动执行git cliff一致性所有成员使用同一份配置与同一版本的工具避免本地环境差异可审计CI 生成的每次变更都以独立提交commit形式记录配合chore(release): Update CHANGELOG这样的提交信息历史清晰可追溯。SourceHut Builds 的.build.yml采用 YAML 描述构建环境天然适合这种拉取源码 → 运行工具 → 回推结果的轻量任务。官方文档 website/docs/sourcehut.md 即为此场景提供了可直接复制的完整方案下文将逐段拆解。完整工作流一份可直接运行的 .build.yml以下配置来自 website/docs/sourcehut.md 的核心示例它完成生成 changelog → 提交 → 推回全流程image: alpine/edge packages: - git-cliff secrets: - your-builds.sr.ht-secret sources: - git://gitgit.sr.ht:~username/repo-name environment: dir: repo-name source: your-source tasks: - git-cliff: | cd $dir git cliff -o CHANGELOG.md ssh-keyscan -t rsa git.sr.ht ~/.ssh/known_hosts git remote set-url origin $source git checkout main git add CHANGELOG.md git commit -m chore(release): Update CHANGELOG git push -o skip-ci逐字段拆解字段取值作用imagealpine/edge指定构建镜像。alpine/edge仓库包含git-cliff包可直接通过apk安装详见 website/docs/installation/alpine-linux.mdpackages- git-cliff在镜像启动后预装 git-cliff无需手动apk addsecrets构建机私钥将 SourceHut 私钥注入构建环境用于向git.sr.ht认证推送sourcesgit://...构建机启动时自动 clone 你的仓库到工作目录environmentdir/source定义任务内可直接引用的变量减少重复书写tasksgit-cliff任务实际执行的命令序列任务内命令按顺序运行核心原理git-cliff 命令在 CI 中的执行链路任务里的git cliff -o CHANGELOG.md是整个流程的心脏。从命令行参数定义 git-cliff/src/args.rs 可以看到-o/--output用于指定输出文件路径且支持不带路径的简写形式——此时默认输出到CHANGELOG.md默认值由git-cliff-core的DEFAULT_OUTPUT常量提供见 git-cliff-core/src/lib.rs。因此上面的写法与git cliff -o、git cliff --output CHANGELOG.md等价。命令的实际执行入口在 git-cliff/src/main.rs程序先解析参数并调用git_cliff::run()生成 changelog随后根据--output参数或配置中changelog.output决定写入目标——是指定文件还是标准输出。流程可概括为main.rs解析 CLI 参数设置日志级别-v对应 debug-vv对应 tracerun()读取配置、遍历 Git 标签与提交、应用commit_parsers与模板渲染根据输出路径将结果写入CHANGELOG.md或 stdout。值得注意的是git-cliff/src/main.rs 中output的取值优先来自命令行参数其次才回落到配置文件的changelog.output。这意味着在 CI 脚本里显式传-o CHANGELOG.md可以覆盖仓库内任何配置文件中定义的输出路径行为完全可控。环境准备密钥与占位符替换按照 website/docs/sourcehut.md 的说明首次配置需要完成 4 个步骤1. 生成专用 SSH 密钥ssh-keygen -t ed25519 -C builds.sr.ht -f ~/.ssh/builds-srht使用ed25519而非 RSA 可以获得更短的密钥与更快的握手-C指定注释便于日后区分该密钥用途。2. 将公钥加入 SourceHut 账户把上一步生成的~/.ssh/builds-srht.pub公钥内容添加到 SourceHut 账户的 SSH keys 页面meta.sr.ht 的 Keys 管理入口。这一步让构建机推送时能被git.sr.ht识别为该账户的合法来源。3. 将私钥注册为 Builds 机密把~/.ssh/builds-srht私钥作为 secret 添加到 builds.sr.ht 的 Secrets 管理页面。注册后SourceHut 会在构建环境中把该私钥以~/.ssh/secret-name的形式暴露给任务使用。4. 替换 .build.yml 中的占位符对照上文完整示例需要替换 4 处占位符替换为示例your-builds.sr.ht-secret第 3 步中注册的 secret 名称builds-srhtusername你的 SourceHut 用户名alicerepo-name仓库名称my-projectyour-source仓库的 SSH 地址gitgit.sr.ht:~alice/my-project提示your-source通常是gitgit.sr.ht:~username/repo-name形式与sources中声明的地址保持同构但走 SSH 协议以便推送。任务脚本逐行解析从生成到推送的完整链路任务块中的 shell 脚本是整个自动化的精华逐行拆解如下1. 进入仓库目录cd $dir$dir来自environment段即sources中 clone 下来的目录名与仓库同名。SourceHut 默认把sources克隆到构建工作目录下。2. 生成变更日志git cliff -o CHANGELOG.md在仓库根目录执行 git-cliff。它会自动发现项目中的cliff.toml/.cliff.toml/.config/cliff.toml配置发现逻辑见 git-cliff/src/args.rs若没有则回落到内置默认配置将生成的 changelog 写入CHANGELOG.md。若仓库尚未配置可先用git cliff --init生成默认配置再提交到仓库参见 website/docs/index.md 的快速开始。3. 信任 SourceHut 主机ssh-keyscan -t rsa git.sr.ht ~/.ssh/known_hosts由于构建环境是全新的~/.ssh/known_hosts为空。直接git push会因 host key 校验失败而中止所以先用ssh-keyscan抓取git.sr.ht的 RSA 公钥并写入 known_hosts跳过首次连接确认。4. 切换推送协议git remote set-url origin $source$source为 SSH 形式地址。构建机初始 clone 用的是git://协议只读推送前必须切换到 SSH 地址否则无法写回远端。5. 提交变更git checkout main git add CHANGELOG.md git commit -m chore(release): Update CHANGELOGgit checkout main确保在目标分支上操作避免构建机默认 checkout 的 HEAD 不在main提交信息chore(release): Update CHANGELOG是标准的 Conventional Commits 类型即使后续再对该提交运行 git-cliff它也会被归入chore分组不会污染下一版 changelog 的语义分类。6. 推送并跳过 CI 递归git push -o skip-ci-o skip-ci是 SourceHut 特有的推送选项push option通知 builds.sr.ht 忽略本次推送触发的构建。这是防止无限递归的关键若省略更新CHANGELOG.md的提交会再次触发构建构建再次推送、再次触发……形成死循环。深入源码git-cliff 在 CI 中的输出与兼容性保证输出优先级结合 git-cliff/src/main.rs 的源码输出目标的决策顺序为命令行--output 配置changelog.output 标准输出。在 CI 场景下只要配置中未写死output-o CHANGELOG.md就能稳定生效反过来若你想在 CI 中只打印不落盘例如先人工审查则不加-o即可让结果流向 stdout配合构建日志查看。git cliff与git-cliff的互换性示例脚本使用了git cliff子命令形式。根据 website/docs/index.md 的说明在安装了 Git 的环境中git cliff与git-cliff带连字符可互换使用SourceHut 的 Alpine 镜像自带 Git因此两种写法均可。若希望脚本更通用例如未来迁移到不含 Git 的环境可改用git-cliff。Alpine 包与 Dockerfile 的佐证Alpine 可用性git-cliff 已打包进 Alpine Edge 的 community 仓库website/docs/installation/alpine-linux.md 明确apk add git-cliff即可安装这正是.build.yml中packages直接声明git-cliff的前提容器行为参考仓库根目录的 Dockerfile 展示了官方容器镜像的构建方式以 Debian slim 为基础、内置git与安全目录豁免配置。它验证了 git-cliff 二进制在容器化 CI 环境中的标准运行形态SourceHut 的 Alpine 环境遵循同样的二进制 Git 仓库运行模型。常见问题与排错建议现象可能原因处理建议构建在git push处失败私钥未注册为 secret或 secret 名称与占位符不一致核对secrets段名称与 builds.sr.ht Secrets 页面中的注册名推送被拒绝权限不足公钥未添加到 SourceHut 账户检查 meta.sr.ht 的 Keys 页面是否包含builds-srht.pubssh-keyscan报 host key 冲突多次运行后 known_hosts 残留旧条目在任务开头先清空或改用-H选项重新扫描changelog 未包含最新提交main分支与构建机 checkout 的默认分支不一致确认git checkout main与仓库默认分支名一致若默认分支为master同步修改构建无限循环触发推送时未携带-o skip-ci确保git push -o skip-ci保留在脚本末尾扩展将 changelog 生成与版本发布结合在 SourceHut 构建中你还可以把 git-cliff 的版本能力一并纳入自动化。例如先计算下一版本号再生成 changeloggit cliff --bump --unreleased --output CHANGELOG.md git commit -m chore(release): Update CHANGELOG git push -o skip-ci--bump会基于未发布提交自动推导 SemVer 版本fix:递增 PATCH、feat:递增 MINOR、破坏性变更递增 MAJOR详见 website/docs/usage/bump-version.md如需在发布标签后生成可在任务中先git tag再运行git cliffgit-cliff 会依据 config/cliff.toml 中的tag_pattern识别标签并分段生成各版本 changelog。这样一套构建即可同时完成版本号 变更日志 提交推送的发布流水线。小结通过 SourceHut Builds 的.build.yml配合git-cliff的 Alpine 软件包与 SSH 密钥认证你可以在每次代码合并后自动生成并回推CHANGELOG.md。核心要点可以归结为四句话用packages预装工具、用secrets注入推送权限、用ssh-keyscan解决首次信任、用git push -o skip-ci防止 CI 死循环。对照本仓库的 示例配置 和 命令行用法文档 按需调整后即可将这套自动化直接应用到自己的 SourceHut 项目中。【免费下载链接】git-cliffA highly customizable Changelog Generator that follows Conventional Commit specifications ⛰️项目地址: https://gitcode.com/gh_mirrors/gi/git-cliff创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考