Back to Details

git-release

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Git 自动发布（GitHub / GitLab）

Automated Git Releases (GitHub / GitLab)

功能概述

Feature Overview

自动化 GitHub/GitLab Release 发布流程，遵循语义化版本（Semantic Versioning）规范。自动分析 Git 提交记录并更新 CHANGELOG.md，然后确定合适的版本号并完成发布。
Automate GitHub/GitLab Release workflows, following Semantic Versioning specifications. Automatically analyze Git commit history and update CHANGELOG.md, then determine the appropriate version number and complete the release.

发布流程

Release Workflow

步骤 0: 验证 Git 平台

Step 0: Verify Git Platform

检查当前仓库的 Git 平台类型：
bash
git remote get-url origin
解析并验证 URL 格式：
GitHub：
  • HTTPS: 
    https://github.com/owner/repo.git
  • SSH: 
    git@github.com:owner/repo.git
  • 提取 
    owner/repo
    用于后续创建 GitHub Release
GitLab：
  • HTTPS: 
    https://gitlab.com/owner/repo.git
    或自托管 
    https://gitlab.example.com/owner/repo.git
  • SSH: 
    git@gitlab.com:owner/repo.git
    或 
    git@gitlab.example.com:owner/repo.git
  • 提取 
    owner/repo
    （或完整路径用于自托管）用于后续创建 GitLab Release
既不是 GitHub 也不是 GitLab：
  • 通知用户此技能仅支持 GitHub 和 GitLab
  • 询问是否仅执行 git tag/push（跳过 Release 创建）
检测到平台后，继续执行步骤 1
Check the Git platform type of the current repository:
bash
git remote get-url origin
Parse and verify URL format:
GitHub:
  • HTTPS: 
    https://github.com/owner/repo.git
  • SSH: 
    git@github.com:owner/repo.git
  • Extract 
    owner/repo
    for subsequent GitHub Release creation
GitLab:
  • HTTPS: 
    https://gitlab.com/owner/repo.git
    or self-hosted 
    https://gitlab.example.com/owner/repo.git
  • SSH: 
    git@gitlab.com:owner/repo.git
    or 
    git@gitlab.example.com:owner/repo.git
  • Extract 
    owner/repo
    (or full path for self-hosted) for subsequent GitLab Release creation
Neither GitHub nor GitLab:
  • Notify users that this skill only supports GitHub and GitLab
  • Ask whether to only execute git tag/push (skip Release creation)
Proceed to Step 1 after platform detection

步骤 1: 分析提交并更新 CHANGELOG

Step 1: Analyze Commits and Update CHANGELOG

自动分析最近的 Git 提交并更新 CHANGELOG.md：
  1. 获取自上次发布以来的提交：
bash
undefined
Automatically analyze recent Git commits and update CHANGELOG.md:
  1. Get commits since last release:
bash
undefined

获取最新标签

Get latest tag

LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")

获取自上次标签之后的提交（如果没有标签则获取所有提交）

Get commits after the latest tag (all commits if no tag exists)

if [ -n "$LATEST_TAG" ]; then git log ${LATEST_TAG}..HEAD --pretty=format:"%h|%s|%an" --reverse else git log --pretty=format:"%h|%s|%an" --reverse fi

2. **解析并分类提交信息**：

使用 Conventional Commits 格式进行分类：
- `feat:` → **Added**（新功能）
- `fix:` → **Fixed**（Bug 修复）
- `break:` 或 `BREAKING CHANGE:` → **Changed**（破坏性变更）
- `refactor:`, `perf:`, `chore:`, `docs:`, `test:`, `style:` → **Changed**（其他变更）

对每个提交信息：
- 提取类别（type）前缀
- 提取 scope（如果有），在描述时显示为 `scope: xxx`
- 清理消息（移除 conventional commit 前缀）
- 按类别分组

3. **更新 CHANGELOG.md**：

读取现有的 CHANGELOG.md 并更新 `[Unreleased]` 部分：

```markdown
if [ -n "$LATEST_TAG" ]; then git log ${LATEST_TAG}..HEAD --pretty=format:"%h|%s|%an" --reverse else git log --pretty=format:"%h|%s|%an" --reverse fi

2. **Parse and categorize commit messages**:

Categorize using Conventional Commits format:
- `feat:` → **Added** (new features)
- `fix:` → **Fixed** (bug fixes)
- `break:` or `BREAKING CHANGE:` → **Changed** (breaking changes)
- `refactor:`, `perf:`, `chore:`, `docs:`, `test:`, `style:` → **Changed** (other changes)

For each commit message:
- Extract category (type) prefix
- Extract scope (if exists), display as `scope: xxx` in description
- Clean message (remove conventional commit prefix)
- Group by category

3. **Update CHANGELOG.md**:

Read existing CHANGELOG.md and update the `[Unreleased]` section:

```markdown

[Unreleased]

[Unreleased]

Added

Added

  • scope: feature 功能描述 1
  • 功能描述 2
  • scope: feature description 1
  • feature description 2

Changed

Changed

  • scope: refactor 重构/其他变更 3
  • Breaking: 破坏性变更 4
  • scope: refactor/other change 3
  • Breaking: breaking change 4

Fixed

Fixed

  • scope: fix Bug 修复描述

**更新规则**：
- 如果 `[Unreleased]` 部分存在且有内容，追加新提交到相应类别
- 如果 `[Unreleased]` 部分存在但为空，填充分类后的提交
- 如果 `[Unreleased]` 部分不存在，在头部创建新部分

**实现要点**：
- 使用 Edit 工具修改 CHANGELOG.md
- 保留现有的未发布内容（如果有）
- 格式：每个要点简洁明了，使用提交消息正文
- 如果提交包含 scope，在描述前添加 `scope: xxx`
- 破坏性变更添加 `**Breaking**:` 前缀以突出显示

4. **向用户展示摘要**：

显示添加到 CHANGELOG 的内容摘要：
分析了 X 个提交（自 v{version} 以来）：
  • 3 个 Added（新功能）
  • 2 个 Changed（包括 1 个破坏性变更）
  • 1 个 Fixed（Bug 修复）
undefined
  • scope: fix bug description

**Update Rules**:
- If `[Unreleased]` section exists and has content, append new commits to corresponding categories
- If `[Unreleased]` section exists but is empty, fill with categorized commits
- If `[Unreleased]` section does not exist, create a new section at the top

**Implementation Key Points**:
- Use Edit tool to modify CHANGELOG.md
- Preserve existing unreleased content (if any)
- Format: each bullet is concise, using commit message body
- If commit includes scope, add `scope: xxx` before description
- Add `**Breaking**:` prefix to breaking changes for emphasis

4. **Show summary to user**:

Display summary of content added to CHANGELOG:
Analyzed X commits (since v{version}):
  • 3 Added (new features)
  • 2 Changed (including 1 breaking change)
  • 1 Fixed (bug fix)
undefined

步骤 2: 分析未发布变更

Step 2: Analyze Unreleased Changes

读取更新后的 CHANGELOG.md 并检查 
[Unreleased]
部分，对变更进行分类：
  • MAJOR (X.0.0): 包含破坏性变更，需要主版本升级
  • MINOR (x.Y.0): 添加了新功能
  • PATCH (x.y.Z): 仅有 Bug 修复
版本决策矩阵：
存在破坏性变更 → MAJOR
有新功能（无破坏性） → MINOR
仅 Bug 修复 → PATCH
Read updated CHANGELOG.md and check 
[Unreleased]
section, categorize changes:
  • MAJOR (X.0.0): Contains breaking changes, requires major version upgrade
  • MINOR (x.Y.0): New features added
  • PATCH (x.y.Z): Only bug fixes
Version Decision Matrix:
Breaking changes exist → MAJOR
New features (no breaking changes) → MINOR
Only bug fixes → PATCH

步骤 3: 确定新版本号

Step 3: Determine New Version Number

  1. 从 git 标签获取当前版本：
    git describe --tags --abbrev=0
  2. 解析版本号（MAJOR.MINOR.PATCH）
  3. 根据分类的变更应用版本升级
  4. 向用户展示决策并请求确认
示例展示：
当前版本：1.2.3
未发布变更：
- Breaking: 破坏性变更说明
- Added: 新功能描述
- Fixed: Bug 修复说明

推荐版本：2.0.0（检测到破坏性变更）
确认？(yes/no)
  1. Get current version from git tags: 
    git describe --tags --abbrev=0
  2. Parse version number (MAJOR.MINOR.PATCH)
  3. Apply version upgrade based on categorized changes
  4. Show decision to user and request confirmation
Example Display:
Current version: 1.2.3
Unreleased changes:
- Breaking: breaking change description
- Added: new feature description
- Fixed: bug fix description

Recommended version: 2.0.0 (breaking changes detected)
Confirm? (yes/no)

步骤 4: 更新 CHANGELOG.md

Step 4: Update CHANGELOG.md

  1. 将 
    ## [Unreleased]
    替换为 
    ## [X.Y.Z] - YYYY-MM-DD
  2. 在底部添加版本链接（根据平台）：
GitHub：
markdown
[X.Y.Z]: https://github.com/owner/repo/compare/vA.B.C...vX.Y.Z
GitLab：
markdown
[X.Y.Z]: https://gitlab.com/owner/repo/-/compare/vA.B.C...vX.Y.Z
GitLab 自托管：
markdown
[X.Y.Z]: https://gitlab.example.com/owner/repo/-/compare/vA.B.C...vX.Y.Z
  1. 提交：
    git commit -m "chore: release vX.Y.Z"
  1. Replace 
    ## [Unreleased]
    with 
    ## [X.Y.Z] - YYYY-MM-DD
  2. Add version link at the bottom (based on platform):
GitHub:
markdown
[X.Y.Z]: https://github.com/owner/repo/compare/vA.B.C...vX.Y.Z
GitLab:
markdown
[X.Y.Z]: https://gitlab.com/owner/repo/-/compare/vA.B.C...vX.Y.Z
Self-hosted GitLab:
markdown
[X.Y.Z]: https://gitlab.example.com/owner/repo/-/compare/vA.B.C...vX.Y.Z
  1. Commit: 
    git commit -m "chore: release vX.Y.Z"

步骤 5: 创建并推送标签

Step 5: Create and Push Tag

bash
git tag -a vX.Y.Z -m "Release vX.Y.Z"
git push origin main
git push origin vX.Y.Z
bash
git tag -a vX.Y.Z -m "Release vX.Y.Z"
git push origin main
git push origin vX.Y.Z

步骤 6: 创建 Release

Step 6: Create Release

GitHub Release

GitHub Release

使用 
gh release create
创建格式化的发布说明：
bash
gh release create vX.Y.Z \
  --title "vX.Y.Z" \
  --notes "## What's Changed
Use 
gh release create
to create formatted release notes:
bash
gh release create vX.Y.Z \
  --title "vX.Y.Z" \
  --notes "## What's Changed

Added

Added

  • scope: feature 新功能描述 1
  • 新功能描述 2
  • scope: feature description 1
  • feature description 2

Fixed

Fixed

  • scope: fix Bug 修复描述
  • scope: fix bug description

Changed

Changed

  • 其他变更描述
Full Changelog: https://github.com/owner/repo/compare/vA.B.C...vX.Y.Z"

**Release Notes 格式规范**：
- 使用英文标题 `## What's Changed`
- 使用 `### Added`、`### Fixed`、`### Changed` 分类
- 每个条目使用 `-` 开头，简洁明了
- 如果提交包含 scope，在描述前添加 `scope: xxx`
- 破坏性变更使用 `**Breaking**:` 前缀
- 链接文本使用 `**Full Changelog**:`
- 如果某个分类为空，则省略该分类
- 从 CHANGELOG.md 中提取对应版本的 `Added`、`Fixed`、`Changed` 内容

**重要提示**：如果 gh 命令因认证失败，提供用户：
1. 在 GitHub Web UI 手动创建发布的链接
2. 格式化的发布说明内容供复制粘贴
  • other change description
Full Changelog: https://github.com/owner/repo/compare/vA.B.C...vX.Y.Z"

**Release Notes Format Specifications**:
- Use English title `## What's Changed`
- Use `### Added`, `### Fixed`, `### Changed` for categorization
- Each entry starts with `-`, concise and clear
- If commit includes scope, add `scope: xxx` before description
- Add `**Breaking**:` prefix to breaking changes
- Use `**Full Changelog**:` for link text
- Omit empty categories
- Extract corresponding version's `Added`, `Fixed`, `Changed` content from CHANGELOG.md

**Important Notes**: If gh command fails due to authentication issues, provide users with:
1. Link to manually create release in GitHub Web UI
2. Formatted release notes content for copy-paste

GitLab Release

GitLab Release

使用 
glab release create
创建格式化的发布说明：
bash
glab release create vX.Y.Z \
  --name "vX.Y.Z" \
  --notes "## What's Changed
Use 
glab release create
to create formatted release notes:
bash
glab release create vX.Y.Z \
  --name "vX.Y.Z" \
  --notes "## What's Changed

Added

Added

  • scope: feature 新功能描述 1
  • 新功能描述 2
  • scope: feature description 1
  • feature description 2

Fixed

Fixed

  • scope: fix Bug 修复描述
  • scope: fix bug description

Changed

Changed

  • 其他变更描述
Full Changelog: https://gitlab.com/owner/repo/-/compare/vA.B.C...vX.Y.Z"

**Release Notes 格式规范**：与 GitHub Release 相同，使用统一的 `## What's Changed` 格式

**重要提示**：如果 glab 命令因认证失败，提供用户：
1. 在 GitLab Web UI 手动创建发布的链接
2. 格式化的发布说明内容供复制粘贴

**GitLab 自托管**：需要先配置 CLI 的主机地址：

```bash
glab config set host gitlab.example.com
  • other change description
Full Changelog: https://gitlab.com/owner/repo/-/compare/vA.B.C...vX.Y.Z"

**Release Notes Format Specifications**: Same as GitHub Release, use unified `## What's Changed` format

**Important Notes**: If glab command fails due to authentication issues, provide users with:
1. Link to manually create release in GitLab Web UI
2. Formatted release notes content for copy-paste

**Self-hosted GitLab**: Need to configure CLI host address first:

```bash
glab config set host gitlab.example.com

错误处理

Error Handling

  • 不支持的 Git 平台：通知用户此技能仅支持 GitHub 和 GitLab，询问是否仅执行 git tag/push
  • 没有未发布变更：通知用户并询问是否继续
  • Git 工作区不干净：中止并要求用户先提交/暂存变更
  • 认证失败：提供 Web UI 备选方案
  • 推送冲突：指示用户先 pull/rebase 再重试
  • 未配置远程仓库：中止并要求用户先配置远程仓库
  • Unsupported Git Platform: Notify users that this skill only supports GitHub and GitLab, ask whether to only execute git tag/push
  • No Unreleased Changes: Notify users and ask whether to proceed
  • Dirty Git Workspace: Abort and require users to commit/stage changes first
  • Authentication Failure: Provide Web UI alternative
  • Push Conflict: Instruct users to pull/rebase first then retry
  • No Remote Repository Configured: Abort and require users to configure remote repository first

CHANGELOG 格式

CHANGELOG Format

期望使用 Keep a Changelog 格式：
markdown
undefined
Expect to use Keep a Changelog format:
markdown
undefined

[Unreleased]

[Unreleased]

Added

Added

  • scope: feature 新功能描述
  • scope: feature description

Changed

Changed

  • Breaking: 不兼容的变更
  • Breaking: incompatible change

Fixed

Fixed

  • scope: fix Bug 修复描述
  • scope: fix bug description

[1.0.0] - YYYY-MM-DD

[1.0.0] - YYYY-MM-DD

...
undefined
...
undefined

Release Notes 格式规范

Release Notes Format Specifications

创建 Release 时，必须使用以下统一的格式模板，以确保所有版本的一致性：
markdown
undefined
When creating Release, must use the following unified format template to ensure consistency across all versions:
markdown
undefined

What's Changed

What's Changed

Added

Added

  • scope: feature 新功能描述 1
  • 新功能描述 2
  • scope: feature description 1
  • feature description 2

Fixed

Fixed

  • scope: fix Bug 修复描述
  • scope: fix bug description

Changed

Changed

  • 其他变更描述（重构、性能优化等）
  • Breaking: 破坏性变更说明（如有）
Full Changelog: https://github.com/owner/repo/compare/vA.B.C...vX.Y.Z

**格式要求**：
1. **标题固定**：使用 `## What's Changed`（英文，保持历史版本一致性）
2. **分类标准**：
   - `### Added`：新功能
   - `### Fixed`：Bug 修复
   - `### Changed`：其他变更（重构、性能优化、文档等）
3. **scope 显示**：如果提交包含 scope，在描述前添加 `scope: xxx`
4. **破坏性变更**：在 Changed 中使用 `**Breaking**:` 前缀突出显示
5. **链接文本**：使用 `**Full Changelog**:`（英文）
6. **空分类省略**：如果某个分类没有内容，则省略该分类
7. **内容来源**：从 CHANGELOG.md 中提取对应版本的内容

**示例 1 - 仅有新功能**：
```markdown
  • other change descriptions (refactoring, performance optimization, etc.)
  • Breaking: breaking change description (if any)
Full Changelog: https://github.com/owner/repo/compare/vA.B.C...vX.Y.Z

**Format Requirements**:
1. **Fixed Title**: Use `## What's Changed` (English, maintain consistency with historical versions)
2. **Categorization Standards**:
   - `### Added`: New features
   - `### Fixed`: Bug fixes
   - `### Changed`: Other changes (refactoring, performance optimization, documentation, etc.)
3. **Scope Display**: If commit includes scope, add `scope: xxx` before description
4. **Breaking Changes**: Use `**Breaking**:` prefix in Changed category for emphasis
5. **Link Text**: Use `**Full Changelog**:` (English)
6. **Omit Empty Categories**: If a category has no content, omit it
7. **Content Source**: Extract corresponding version's content from CHANGELOG.md

**Example 1 - Only New Features**:
```markdown

What's Changed

What's Changed

Added

Added

  • scope: feature 支持新的验证规则
  • 新增配置项支持自定义行为
Full Changelog: https://github.com/owner/repo/compare/v1.0.14...v1.0.15

**示例 2 - 多分类混合**：
```markdown
  • scope: feature support new validation rules
  • add configuration item for custom behavior
Full Changelog: https://github.com/owner/repo/compare/v1.0.14...v1.0.15

**Example 2 - Mixed Categories**:
```markdown

What's Changed

What's Changed

Added

Added

  • scope: feature 新增 trim 配置支持
  • 新增命名参数支持
  • scope: feature add trim configuration support
  • add named parameter support

Fixed

Fixed

  • 修复数据处理时的空值问题
  • fix null value issue during data processing

Changed

Changed

  • CI: 优化测试运行策略
Full Changelog: https://github.com/owner/repo/compare/v1.0.13...v1.0.14

**示例 3 - 仅 Bug 修复**：
```markdown
  • CI: optimize test execution strategy
Full Changelog: https://github.com/owner/repo/compare/v1.0.13...v1.0.14

**Example 3 - Only Bug Fixes**:
```markdown

What's Changed

What's Changed

Fixed

Fixed

  • scope: fix 修复嵌套对象的验证问题
Full Changelog: https://github.com/owner/repo/compare/v1.0.12...v1.0.13

**从 CHANGELOG 提取内容时**：
- 保留 CHANGELOG 中的原始描述
- 保持分类结构（Added/Fixed/Changed）
- 保留 scope 前缀（如果有）
- 移除日期和版本号（这些在 Release 标题中已有）
- 确保 Full Changelog 链接正确
  • scope: fix nested object validation issue
Full Changelog: https://github.com/owner/repo/compare/v1.0.12...v1.0.13

**When Extracting Content from CHANGELOG**:
- Preserve original descriptions in CHANGELOG
- Maintain categorization structure (Added/Fixed/Changed)
- Preserve scope prefix (if any)
- Remove date and version number (already included in Release title)
- Ensure Full Changelog link is correct

平台 CLI 工具

Platform CLI Tools

GitHub

GitHub

  • Requires 
    gh
    CLI tool installation
  • GitHub token needs 
    repo
    and 
    workflow
    permissions
  • Installation: https://cli.github.com/

GitLab

GitLab

Conventional Commits 支持

Conventional Commits Support

此技能基于 Conventional Commits 规范解析提交信息：
类型分类说明
feat:
Added新功能
fix:
FixedBug 修复
break:
/ 
BREAKING CHANGE:
Changed破坏性变更
refactor:
Changed代码重构
perf:
Changed性能优化
chore:
Changed构建/工具链更新
docs:
Changed文档更新
test:
Changed测试相关
style:
Changed代码风格（不影响功能）
Scope 支持：
  • 如果提交信息包含 scope（如 
    feat(api): 添加新接口
    ），会在描述中显示为 
    scope: api 添加新接口
  • Scope 格式：
    type(scope): description
    或 
    type!: description
    （破坏性变更）
This skill parses commit messages based on Conventional Commits specification:
TypeCategoryDescription
feat:
AddedNew feature
fix:
FixedBug fix
break:
/ 
BREAKING CHANGE:
ChangedBreaking change
refactor:
ChangedCode refactoring
perf:
ChangedPerformance optimization
chore:
ChangedBuild/toolchain updates
docs:
ChangedDocumentation updates
test:
ChangedTest-related changes
style:
ChangedCode style (no functional impact)
Scope Support:
  • If commit message includes scope (e.g., 
    feat(api): add new interface
    ), it will be displayed as 
    scope: api add new interface
    in description
  • Scope format: 
    type(scope): description
    or 
    type!: description
    (breaking change)

使用示例

Usage Examples

  1. 发布新版本：用户说"发布新版本"或"创建 release"
  2. 版本升级：用户提到版本号提升或打标签
  3. 完成重要功能：用户添加了重要功能或修复了多个 Bug 后
  4. 定期发布：按预定时间发布版本（如每周、每月）
  1. Release New Version: User says "release new version" or "create release"
  2. Version Upgrade: User mentions version number bump or tag creation
  3. Complete Important Features: After user adds important features or fixes multiple bugs
  4. Scheduled Releases: Release versions on a scheduled basis (e.g., weekly, monthly)

注意事项

Notes

  • 确保所有要发布的更改已提交并推送到远程
  • CHANGELOG.md 应存在于仓库根目录
  • GitHub: 需要安装 
    gh
    CLI 工具以创建 GitHub Release
  • GitLab: 需要安装 
    glab
    CLI 工具以创建 GitLab Release
  • 自托管 GitLab 实例需要额外配置 
    glab
    的 host 参数
  • 提交消息建议使用 Conventional Commits 格式以便自动分类
  • Ensure all changes to be released have been committed and pushed to remote
  • CHANGELOG.md should exist in repository root directory
  • GitHub: Requires 
    gh
    CLI tool installation to create GitHub Release
  • GitLab: Requires 
    glab
    CLI tool installation to create GitLab Release
  • Self-hosted GitLab instances require additional configuration of 
    glab
    host parameter
  • It is recommended to use Conventional Commits format for commit messages for automatic categorization