Back to Details

release-management

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Release Management

发布管理

Automate releases with 
gh release
, semantic versioning, and changelog generation.
借助
gh release
、语义化版本控制和变更日志生成实现发布自动化。

Quick Reference

快速参考

Create Release

创建发布

bash
undefined
bash
undefined

Auto-generate notes from PRs

Auto-generate notes from PRs

gh release create v1.2.0 --generate-notes
gh release create v1.2.0 --generate-notes

With custom title

With custom title

gh release create v1.2.0 --title "Version 1.2.0: Performance Update" --generate-notes
gh release create v1.2.0 --title "Version 1.2.0: Performance Update" --generate-notes

Draft release (review before publishing)

Draft release (review before publishing)

gh release create v1.2.0 --draft --generate-notes
gh release create v1.2.0 --draft --generate-notes

Pre-release (beta, rc)

Pre-release (beta, rc)

gh release create v1.2.0-beta.1 --prerelease --generate-notes
gh release create v1.2.0-beta.1 --prerelease --generate-notes

With custom notes

With custom notes

gh release create v1.2.0 --notes "## Highlights
  • New auth system
  • 50% faster search"
gh release create v1.2.0 --notes "## Highlights
  • New auth system
  • 50% faster search"

From notes file

From notes file

gh release create v1.2.0 --notes-file RELEASE_NOTES.md
undefined
gh release create v1.2.0 --notes-file RELEASE_NOTES.md
undefined

List & View Releases

列出与查看发布

bash
undefined
bash
undefined

List all releases

List all releases

gh release list
gh release list

View specific release

View specific release

gh release view v1.2.0
gh release view v1.2.0

View in browser

View in browser

gh release view v1.2.0 --web
gh release view v1.2.0 --web

JSON output

JSON output

gh release list --json tagName,publishedAt,isPrerelease
undefined
gh release list --json tagName,publishedAt,isPrerelease
undefined

Verify Releases (gh CLI 2.86.0+)

验证发布（gh CLI 2.86.0+）

bash
undefined
bash
undefined

Verify release attestation (sigstore)

Verify release attestation (sigstore)

gh release verify v1.2.0
gh release verify v1.2.0

Verify specific asset

Verify specific asset

gh release verify-asset v1.2.0 ./dist/app.zip
gh release verify-asset v1.2.0 ./dist/app.zip

Verify with custom trust policy

Verify with custom trust policy

gh release verify v1.2.0 --owner myorg
undefined
gh release verify v1.2.0 --owner myorg
undefined

Manage Releases

管理发布

bash
undefined
bash
undefined

Edit release

Edit release

gh release edit v1.2.0 --title "New Title" --notes "Updated notes"
gh release edit v1.2.0 --title "New Title" --notes "Updated notes"

Delete release

Delete release

gh release delete v1.2.0
gh release delete v1.2.0

Upload assets

Upload assets

gh release upload v1.2.0 ./dist/app.zip ./dist/app.tar.gz

---
gh release upload v1.2.0 ./dist/app.zip ./dist/app.tar.gz

---

Semantic Versioning

语义化版本控制

text
MAJOR.MINOR.PATCH
  │     │     │
  │     │     └── Bug fixes (backwards compatible)
  │     └──────── New features (backwards compatible)
  └────────────── Breaking changes

Examples:
  1.0.0 → 1.0.1  (patch: bug fix)
  1.0.1 → 1.1.0  (minor: new feature)
  1.1.0 → 2.0.0  (major: breaking change)

Pre-release:
  2.0.0-alpha.1  (early testing)
  2.0.0-beta.1   (feature complete)
  2.0.0-rc.1     (release candidate)
text
MAJOR.MINOR.PATCH
  │     │     │
  │     │     └── Bug fixes (backwards compatible)
  │     └──────── New features (backwards compatible)
  └────────────── Breaking changes

Examples:
  1.0.0 → 1.0.1  (patch: bug fix)
  1.0.1 → 1.1.0  (minor: new feature)
  1.1.0 → 2.0.0  (major: breaking change)

Pre-release:
  2.0.0-alpha.1  (early testing)
  2.0.0-beta.1   (feature complete)
  2.0.0-rc.1     (release candidate)

Release Workflow

发布工作流

Standard Release

标准发布

bash
undefined
bash
undefined

1. Ensure main is up to date

1. Ensure main is up to date

git checkout main git pull origin main
git checkout main git pull origin main

2. Determine version bump

2. Determine version bump

Check commits since last release

Check commits since last release

gh release view --json tagName -q .tagName # Current: v1.2.3 git log v1.2.3..HEAD --oneline
gh release view --json tagName -q .tagName # Current: v1.2.3 git log v1.2.3..HEAD --oneline

3. Create and push tag

3. Create and push tag

git tag -a v1.3.0 -m "Release v1.3.0" git push origin v1.3.0
git tag -a v1.3.0 -m "Release v1.3.0" git push origin v1.3.0

4. Create GitHub release

4. Create GitHub release

gh release create v1.3.0
--title "v1.3.0: Feature Name"
--generate-notes
gh release create v1.3.0
--title "v1.3.0: Feature Name"
--generate-notes

5. Close milestone if used

5. Close milestone if used

gh api -X PATCH repos/:owner/:repo/milestones/5 -f state=closed
undefined
gh api -X PATCH repos/:owner/:repo/milestones/5 -f state=closed
undefined

Hotfix Release

热修复发布

bash
undefined
bash
undefined

1. Branch from release tag

1. Branch from release tag

git checkout -b hotfix/v1.2.4 v1.2.3
git checkout -b hotfix/v1.2.4 v1.2.3

2. Fix and commit

2. Fix and commit

git commit -m "fix: Critical security patch"
git commit -m "fix: Critical security patch"

3. Tag and release

3. Tag and release

git tag -a v1.2.4 -m "Hotfix: Security patch" git push origin v1.2.4 gh release create v1.2.4 --title "v1.2.4: Security Hotfix"
--notes "Critical security fix for authentication bypass"
git tag -a v1.2.4 -m "Hotfix: Security patch" git push origin v1.2.4 gh release create v1.2.4 --title "v1.2.4: Security Hotfix"
--notes "Critical security fix for authentication bypass"

4. Merge fix to main

4. Merge fix to main

git checkout main git cherry-pick <commit-sha> git push origin main

---
git checkout main git cherry-pick <commit-sha> git push origin main

---

Changelog Generation

变更日志生成

Auto-Generated (from PRs)

自动生成（来自PR）

bash
undefined
bash
undefined

GitHub auto-generates from merged PRs

GitHub auto-generates from merged PRs

gh release create v1.2.0 --generate-notes
gh release create v1.2.0 --generate-notes

Output includes:

Output includes:

## What's Changed

## What's Changed

* feat: Add user auth by @dev in #123

* feat: Add user auth by @dev in #123

* fix: Login redirect by @dev in #124

* fix: Login redirect by @dev in #124

* docs: Update README by @dev in #125

* docs: Update README by @dev in #125

undefined
undefined

Custom Changelog Template

自定义变更日志模板

Create 
.github/release.yml
:
yaml
changelog:
  categories:
    - title: "Breaking Changes"
      labels:
        - "breaking"
    - title: "New Features"
      labels:
        - "enhancement"
        - "feature"
    - title: "Bug Fixes"
      labels:
        - "bug"
        - "fix"
    - title: "Documentation"
      labels:
        - "documentation"
    - title: "Other Changes"
      labels:
        - "*"
创建
.github/release.yml
文件：
yaml
changelog:
  categories:
    - title: "Breaking Changes"
      labels:
        - "breaking"
    - title: "New Features"
      labels:
        - "enhancement"
        - "feature"
    - title: "Bug Fixes"
      labels:
        - "bug"
        - "fix"
    - title: "Documentation"
      labels:
        - "documentation"
    - title: "Other Changes"
      labels:
        - "*"

Manual CHANGELOG.md

手动维护CHANGELOG.md

markdown
undefined
markdown
undefined

Changelog

Changelog

[1.3.0] - 2026-01-15

[1.3.0] - 2026-01-15

Added

Added

  • User authentication system (#123)
  • Dark mode support (#125)
  • User authentication system (#123)
  • Dark mode support (#125)

Changed

Changed

  • Improved search performance (#126)
  • Improved search performance (#126)

Fixed

Fixed

  • Login redirect loop (#124)
  • Login redirect loop (#124)

Security

Security

  • Updated dependencies for CVE-2026-1234

---
  • Updated dependencies for CVE-2026-1234

---

Automation with GitHub Actions

借助GitHub Actions实现自动化

yaml
undefined
yaml
undefined

.github/workflows/release.yml

.github/workflows/release.yml

name: Release
on: push: tags: - 'v*'
jobs: release: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4
  - name: Build
    run: npm run build

  - name: Create Release
    env:
      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    run: |
      gh release create ${{ github.ref_name }} \
        --generate-notes \
        ./dist/*.zip

---
name: Release
on: push: tags: - 'v*'
jobs: release: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4
  - name: Build
    run: npm run build

  - name: Create Release
    env:
      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    run: |
      gh release create ${{ github.ref_name }} \
        --generate-notes \
        ./dist/*.zip

---

Version Bumping Script

版本升级脚本

bash
#!/bin/bash
bash
#!/bin/bash

bump-version.sh

bump-version.sh

CURRENT=$(gh release view --json tagName -q .tagName | sed 's/v//') IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT"
case $1 in major) NEW="$((MAJOR + 1)).0.0" ;; minor) NEW="$MAJOR.$((MINOR + 1)).0" ;; patch) NEW="$MAJOR.$MINOR.$((PATCH + 1))" ;; *) echo "Usage: $0 [major|minor|patch]"; exit 1 ;; esac
echo "Bumping $CURRENT -> $NEW" git tag -a "v$NEW" -m "Release v$NEW" git push origin "v$NEW" gh release create "v$NEW" --generate-notes

Usage:

```bash
./bump-version.sh patch  # 1.2.3 -> 1.2.4
./bump-version.sh minor  # 1.2.4 -> 1.3.0
./bump-version.sh major  # 1.3.0 -> 2.0.0
CURRENT=$(gh release view --json tagName -q .tagName | sed 's/v//') IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT"
case $1 in major) NEW="$((MAJOR + 1)).0.0" ;; minor) NEW="$MAJOR.$((MINOR + 1)).0" ;; patch) NEW="$MAJOR.$MINOR.$((PATCH + 1))" ;; *) echo "Usage: $0 [major|minor|patch]"; exit 1 ;; esac
echo "Bumping $CURRENT -> $NEW" git tag -a "v$NEW" -m "Release v$NEW" git push origin "v$NEW" gh release create "v$NEW" --generate-notes

使用方法：

```bash
./bump-version.sh patch  # 1.2.3 -> 1.2.4
./bump-version.sh minor  # 1.2.4 -> 1.3.0
./bump-version.sh major  # 1.3.0 -> 2.0.0

Release Checklist

发布检查清单

markdown
undefined
markdown
undefined

Release v1.3.0 Checklist

Release v1.3.0 Checklist

Pre-Release

Pre-Release

  • All PRs merged to main
  • CI/CD passing on main
  • Version numbers updated in package.json/pyproject.toml
  • CHANGELOG.md updated
  • Documentation updated
  • Milestone closed
  • All PRs merged to main
  • CI/CD passing on main
  • Version numbers updated in package.json/pyproject.toml
  • CHANGELOG.md updated
  • Documentation updated
  • Milestone closed

Release

Release

  • Tag created and pushed
  • GitHub release created
  • Release notes reviewed
  • Assets uploaded (if applicable)
  • Tag created and pushed
  • GitHub release created
  • Release notes reviewed
  • Assets uploaded (if applicable)

Post-Release

Post-Release

  • Deployment verified
  • Announcement posted (if applicable)
  • Next milestone created

---
  • Deployment verified
  • Announcement posted (if applicable)
  • Next milestone created

---

Best Practices

最佳实践

  1. Use semantic versioning - Communicate change impact
  2. Draft releases first - Review notes before publishing
  3. Generate notes from PRs - Accurate, automatic history
  4. Close milestone on release - Track completion
  5. Tag main only - Never tag feature branches
  6. Announce breaking changes - Prominent in release notes
  1. 使用语义化版本控制 - 传达变更影响
  2. 先创建草稿发布 - 发布前审核内容
  3. 从PR生成发布说明 - 准确、自动的历史记录
  4. 发布时关闭里程碑 - 跟踪完成情况
  5. 仅在main分支打标 - 切勿为功能分支打标
  6. 公告破坏性变更 - 在发布说明中突出显示

Related Skills

相关技能

  • github-operations: Milestones, issues, and CLI reference
  • git-workflow: Branching and recovery patterns
  • github-operations: 里程碑、问题和CLI参考
  • git-workflow: 分支与恢复模式

References

参考资料

  • Semantic Versioning
  • Release Automation
  • Semantic Versioning
  • Release Automation