github actions 可通过监听 release:published 事件、调用 git log 或 github api 获取版本间提交、结合 conventional-changelog 等工具结构化生成 changelog，并用 action-gh-release 写入 release 描述，需注意权限配置与 pre-release 处理。
GitHub Actions 本身不直接生成发布说明，但能通过组合触发事件、调用工具和 GitHub API，实现自动拉取提交历史、提取变更内容、格式化输出并附加到 Release 页面的全流程。核心不是“写文案”，而是“结构化提取 + 可控渲染”。
基于 release 事件自动抓取变更
发布说明的本质是本次版本与上一版之间的差异摘要。GitHub Actions 可监听 release: published 事件，拿到当前 tag 和前一个 tag，再用 git log 或 GitHub REST API 获取区间内的提交记录。
- 推荐用
actions/checkout@v4并设置fetch-depth: 0，确保能获取完整历史 - 用
github.event.previous_tag_name和github.event.tag_name构建对比范围（如git log ${{ github.event.previous_tag_name }}..${{ github.event.tag_name }}） - 过滤掉合并提交、文档更新等噪音，保留 feat、fix、refactor 等类型前缀的提交
用标准工具生成结构化 changelog
手动拼接文本容易出错且难维护，建议接入成熟工具：
- conventional-changelog：识别符合 Conventional Commits 规范的提交，自动生成带分类（Features / Bug Fixes / Breaking Changes）的 Markdown 日志
- github-release-notes：轻量级 Action，支持按 label 分组、跳过特定 PR、排除 draft PR，输出简洁段落
- 自定义脚本：用 Python 或 Node.js 调用 GitHub API
/repos/{owner}/{repo}/compare接口，解析 commits 和 associated PRs，按需组织内容
把生成内容写入 Release 描述
生成好的 Markdown 内容不能只存在日志里，要真正落到 Release 页面：
- 使用
softprops/action-gh-release@v2或marvinpinto/action-automatic-releases@latest的body输入项传入生成的文本 - 若用原生 API，可用
curl+GITHUB_TOKENPATCH/repos/{owner}/{repo}/releases/{id}，注意 body 需 JSON 编码并转义换行符 - 建议在生成内容头部加一行
## {{ version }} — {{ date }}，保持风格统一
避免常见坑点
看似简单，实操中几个细节容易导致失败或信息缺失：
- Release 创建和说明生成必须在同一个 job 中完成，否则新 release 的 ID 无法传递给后续步骤
-
GITHUB_TOKEN默认权限不包含contents: write以外的操作，修改 release description 需显式声明permissions:块（packages: write不需要，但contents: write必须） - 如果项目使用 pre-release 标签（如
v1.2.0-rc.1），需确保对比逻辑能正确识别上一个 stable 版本，而非最近一个 tag
