---

name: create-github-release locale: wenyan source_locale: en source_commit: 82c77053 fence_basis_commit: 82c77053 translator: "Julius Brussee homage — caveman" translation_date: "2026-04-19" description: > Create a GitHub release with proper tagging, release notes, and optional build artifacts. Covers semantic versioning, changelog generation, and GitHub CLI usage. Use when marking a stable version of software for distribution, publishing a new library or application version, creating release notes for stakeholders, or distributing build artifacts (binaries, tarballs). license: MIT allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: git complexity: basic language: multi tags: github, release, git-tags, changelog, versioning

建 GitHub 發布

建有標之 GitHub 發布，含發布記與可選之建物。

用時

• 標軟件之穩版以布
• 發庫或應用新版
• 為相關者建發布記
• 布建物（二進、tarball）

入

• 必要：版號（語義版本）
• 必要：自上發以來變之概
• 可選：附之建物
• 可選：此為預發否

法

第一步：定版號

循語義版本（MAJOR.MINOR.PATCH）：

變	例	時
MAJOR	1.0.0 -> 2.0.0	破壞性變
MINOR	1.0.0 -> 1.1.0	新功，向後兼容
PATCH	1.0.0 -> 1.0.1	唯修訛

得： 擇版號正映自上發以來變之範圍。

敗則： 若疑變為破壞否，察公 API 之差。出之函刪或簽變皆破壞，需升 MAJOR。

第二步：更項目文件之版

• DESCRIPTION（R 包）
• package.json（Node.js）
• Cargo.toml（Rust）
• pyproject.toml（Python）

得： 版號於宜文件已更並提交版控。

敗則： 若前步已更（如 R 之 usethis::use_version()），驗其合意圖之發版。

第三步：書發布記

建或更變更誌。按類組：

## What's Changed

### New Features
- Added user authentication (#42)
- Support for custom themes (#45)

### Bug Fixes
- Fixed crash on empty input (#38)
- Corrected date parsing in UTC (#41)

### Improvements
- Improved error messages
- Updated dependencies

### Breaking Changes
- `old_function()` renamed to `new_function()` (#50)

**Full Changelog**: https://github.com/user/repo/compare/v1.0.0...v1.1.0

得： 發布記按類組（功、修、破壞），含議題／PR 引以可追。

敗則： 若變難分類，察 git log v1.0.0..HEAD --oneline 以復自上發以來之變列。

第四步：建 git 標

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

得： 註釋標 v1.1.0 存於本地與遠。git tag -l 顯之。

敗則： 若標已存，以 git tag -d v1.1.0 && git push origin :refs/tags/v1.1.0 刪之再建。若推拒，確有遠之寫權。

第五步：建 GitHub 發布

用 GitHub CLI（宜）：

gh release create v1.1.0 \
  --title "v1.1.0" \
  --notes-file CHANGELOG.md

含建物：

gh release create v1.1.0 \
  --title "v1.1.0" \
  --notes "Release notes here" \
  build/app-v1.1.0.tar.gz \
  build/app-v1.1.0.zip

預發：

gh release create v2.0.0-beta.1 \
  --title "v2.0.0 Beta 1" \
  --prerelease \
  --notes "Beta release for testing"

得： 發布現於 GitHub 含標、記、附物（若有）。

敗則： 若 gh 未認證，運 gh auth login。若標未於遠，以 git push origin v1.1.0 先推之。

第六步：自動生發布記

GitHub 可由已合 PR 自動生記：

gh release create v1.1.0 \
  --title "v1.1.0" \
  --generate-notes

於 .github/release.yml 設類：

changelog:
  categories:
    - title: New Features
      labels:
        - enhancement
    - title: Bug Fixes
      labels:
        - bug
    - title: Documentation
      labels:
        - documentation
    - title: Other Changes
      labels:
        - "*"

得： 發布記由已合 PR 題自動生，按標分類。.github/release.yml 控類。

敗則： 若自動記為空，確 PR 已合（非閉）且有標。手書記為退。

第七步：驗發布

# List releases
gh release list

# View specific release
gh release view v1.1.0

得： gh release list 顯新發。gh release view 顯正題、標、記、資。

敗則： 若發缺，察 Actions 頁以見是否有發工作流敗。以 git tag -l 驗標存。

驗

• 版標循語義版本
• git 標指正提交
• 發布記正述變
• 附物（若有）可附可下
• 發布現於 GitHub 庫頁
• 預發旗正設

陷

• 標誤提交：標前宜驗 git log。版升提交後乃標。
• 忘推標：git push 不推標。用 git push --tags 或 git push origin v1.1.0。
• 版式不一：於 v1.0.0 對 1.0.0 中擇一而守之。
• 發布記空：宜供有意之記。用者需知所變。
• 刪而重建標：推後勿改標。若需，建新版代之。

參

• commit-changes — 暫存與提交流
• manage-git-branches — 為發備之分支管
• release-package-version — R 專用發流
• configure-git-repository — Git 設前提
• setup-github-actions-ci — 以 CI 自動發