semantic-release

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

semantic-release

Overview

概述

Automate semantic versioning and release management using semantic-release v25+ (Node.js) following 2025 best practices. Works with all languages (JavaScript, TypeScript, Python, Rust, Go, C++, etc.) via the

@semantic-release/exec

plugin. Create shareable configurations for multi-repository setups, initialize individual projects with automated releases, and configure GitHub Actions workflows with OIDC trusted publishing.

Important: This skill uses semantic-release (Node.js) exclusively, NOT python-semantic-release, even for Python projects. Rationale: 23.5x larger community, 100x+ adoption, better future-proofing.

遵循2025年最佳实践，使用 semantic-release v25+（Node.js） 实现语义化版本控制和发布管理自动化。通过

@semantic-release/exec

插件支持 所有编程语言（JavaScript、TypeScript、Python、Rust、Go、C++等）。可为多仓库环境创建可共享配置，为单个项目初始化自动化发布，并配置基于OIDC可信发布的GitHub Actions工作流。

重要说明：本技能仅使用Node.js版本的semantic-release，即使是Python项目也不使用python-semantic-release。理由：社区规模是其23.5倍，采用量超100倍，未来兼容性更佳。

When to Use This Skill

适用场景

Invoke when:

Setting up local releases for a new project (any language)
Creating shareable semantic-release configuration for organization-wide use
Migrating existing projects to 2025 semantic-release patterns
Troubleshooting semantic-release setup or version bumps
Setting up Python projects (use Node.js semantic-release, NOT python-semantic-release)
Configuring GitHub Actions (optional backup, not recommended as primary due to speed)
Rust workspaces using release-plz (see Rust reference)

在以下场景下调用本技能：

为新项目（任意语言）设置本地发布流程
创建可在组织内复用的semantic-release配置
将现有项目迁移至2025年semantic-release最佳实践
排查semantic-release配置或版本号更新问题
为Python项目配置版本控制（使用Node.js版semantic-release，而非python-semantic-release）
配置GitHub Actions（可选备用方案，不推荐作为主要方式，因速度较慢）
使用release-plz的Rust工作区（参见 Rust 参考文档）

Why Node.js semantic-release

为何选择Node.js版semantic-release

22,900 GitHub stars - Large, active community 1.9M weekly downloads - Proven adoption 126,000 projects using it - Battle-tested at scale 35+ official plugins - Rich ecosystem Multi-language support - Works with any language via

@semantic-release/exec

Do NOT use python-semantic-release. It has a 23.5x smaller community (975 vs 22,900 stars), ~100x less adoption, and is not affiliated with the semantic-release organization.

22,900个GitHub星标 - 庞大且活跃的社区 每周190万次下载量 - 经过验证的广泛采用 126,000个项目在使用 - 经大规模场景检验 35+个官方插件 - 丰富的生态系统 多语言支持 - 通过

@semantic-release/exec

适配任意编程语言

请勿使用python-semantic-release。其社区规模仅为前者的1/23.5（975 vs 22,900星标），采用量约为1/100，且与semantic-release官方组织无关。

Release Workflow Philosophy: Local-First

发布工作流理念：本地优先

Default approach: Run releases locally, not via GitHub Actions.

默认方式：在本地运行发布，而非通过GitHub Actions。

Why Local Releases

为何选择本地发布

Primary argument: GitHub Actions is slow

⏱️ GitHub Actions: 2-5 minute wait for release to complete
⚡ Local release: Instant feedback and file updates
🔄 Immediate workflow continuity - no waiting for CI/CD

Additional benefits:

✅ Instant local file sync -
```
package.json
```
,
```
CHANGELOG.md
```
, tags updated immediately
✅ No pull required - Continue working without
```
git pull
```
after release
✅ Dry-run testing -
```
npm run release:dry
```
to preview changes before release
✅ Offline capable - Can release without CI/CD dependency
✅ Faster iteration - Debug release issues immediately, not through CI logs

核心原因：GitHub Actions速度太慢

⏱️ GitHub Actions：发布完成需等待2-5分钟
⚡ 本地发布：即时反馈和文件更新
🔄 工作流持续进行 - 无需等待CI/CD

额外优势：

✅ 本地文件即时同步 -
```
package.json
```
、
```
CHANGELOG.md
```
、标签立即更新
✅ 无需拉取代码 - 发布后可直接继续工作，无需执行
```
git pull
```
✅ 预演测试 - 使用
```
npm run release:dry
```
在发布前预览变更
✅ 支持离线使用 - 无需依赖CI/CD即可完成发布
✅ 迭代速度更快 - 立即排查发布问题，无需查看CI日志

GitHub Actions: Optional Backup Only

GitHub Actions：仅作为可选备用方案

GitHub Actions workflows are provided as optional automation, not the primary method:

Use for team consistency if required
Backup if local environment unavailable
Not recommended as primary workflow due to speed

GitHub Actions工作流仅作为可选自动化方案，而非主要方式：

若需要团队一致性则使用
本地环境不可用时作为备用
因速度问题，不推荐作为主要工作流

Authentication Setup

认证设置

bash

gh auth login

bash

gh auth login

Browser authentication once

仅需一次浏览器认证

Credentials stored in keyring

凭据存储在密钥环中

All future releases: zero manual intervention

后续所有发布：无需手动干预


**This is the minimum manual intervention possible** for local semantic-release with GitHub plugin functionality.


**这是本地semantic-release结合GitHub插件功能所需的最少手动操作**。

Multi-Account Authentication via mise [env]

通过mise [env]实现多账号认证

For multi-account GitHub setups, use mise

[env]

to set per-directory GH_TOKEN:

toml

undefined

对于多账号GitHub环境，使用mise

[env]

为每个目录设置独立的GH_TOKEN：

toml

undefined

~/your-project/.mise.toml

[env] GH_TOKEN = "{{ read_file(path=env.HOME ~ '/.claude/.secrets/gh-token-accountname') | trim }}" GITHUB_TOKEN = "{{ read_file(path=env.HOME ~ '/.claude/.secrets/gh-token-accountname') | trim }}"


This overrides gh CLI's global authentication, ensuring semantic-release uses the correct account for each directory.

See the [`mise-configuration` skill](../mise-configuration/SKILL.md#github-token-multi-account-patterns) for complete setup.

[env] GH_TOKEN = "{{ read_file(path=env.HOME ~ '/.claude/.secrets/gh-token-accountname') | trim }}" GITHUB_TOKEN = "{{ read_file(path=env.HOME ~ '/.claude/.secrets/gh-token-accountname') | trim }}"


这会覆盖gh CLI的全局认证设置，确保semantic-release为每个目录使用正确的账号。

完整设置请参见 [`mise-configuration` 技能](../mise-configuration/SKILL.md#github-token-multi-account-patterns)。

mise Task Detection

mise任务检测

When

.mise.toml

has release tasks, prefer

mise run

over

npm run

Priority	Condition	Command
1	`.mise.toml` has `[tasks.release:*]`	`mise run release:version`
2	`package.json` has `scripts.release`	`npm run release`
3	Global semantic-release	`semantic-release --no-ci`

See Python Guide for complete mise workflow example.

当

.mise.toml

包含发布任务时，优先使用

mise run

而非

npm run

：

优先级	条件	命令
1	`.mise.toml` 包含 `[tasks.release:*]`	`mise run release:version`
2	`package.json` 包含 `scripts.release`	`npm run release`
3	全局安装的semantic-release	`semantic-release --no-ci`

完整mise工作流示例请参见 Python 指南。

GitHub Actions Policy

GitHub Actions 策略

CRITICAL: No testing or linting in GitHub Actions. See CLAUDE.md for full policy.

Forbidden	Allowed
pytest, npm test, cargo test	semantic-release
ruff, eslint, clippy, prettier	CodeQL, npm audit
mypy	Deployment, Dependabot

关键规则：禁止在GitHub Actions中执行测试或代码检查。完整策略请参见CLAUDE.md。

禁止操作	允许操作
pytest、npm test、cargo test	semantic-release
ruff、eslint、clippy、prettier	CodeQL、npm audit
mypy	部署、Dependabot

Separation of Concerns (4-Level Architecture)

关注点分离（4层架构）

semantic-release configuration follows a hierarchical, composable pattern:

Level 1: Skill -

${CLAUDE_PLUGIN_ROOT}/skills/semantic-release/

(Generic templates, system-wide tool) Level 2: User Config -

~/semantic-release-config/

(

@username/semantic-release-config

) Level 3: Organization Config - npm registry (

@company/semantic-release-config

) Level 4: Project Config -

.releaserc.yml

in project root

semantic-release配置遵循分层、可组合的模式：

第1层：技能 -

${CLAUDE_PLUGIN_ROOT}/skills/semantic-release/

（通用模板，系统级工具） 第2层：用户配置 -

~/semantic-release-config/

（

@username/semantic-release-config

） 第3层：组织配置 - npm注册表（

@company/semantic-release-config

） 第4层：项目配置 - 项目根目录下的

.releaserc.yml

Configuration Precedence

配置优先级

Level 4 (Project) → overrides → Level 3 (Org) → overrides → Level 2 (User) → overrides → Defaults

第4层（项目） → 覆盖 → 第3层（组织） → 覆盖 → 第2层（用户） → 覆盖 → 默认配置

Conventional Commits Format

约定式提交格式

semantic-release analyzes commit messages to determine version bumps:

<type>(<scope>): <subject>

semantic-release通过分析提交信息来决定版本号更新规则：

<type>(<scope>): <subject>

Version Bump Rules (Default)

默认版本号更新规则

```
feat:
```
→ MINOR version bump (0.1.0 → 0.2.0)
```
fix:
```
→ PATCH version bump (0.1.0 → 0.1.1)
```
BREAKING CHANGE:
```
or
```
feat!:
```
→ MAJOR version bump (0.1.0 → 1.0.0)
```
docs:
```
,
```
chore:
```
,
```
style:
```
,
```
refactor:
```
,
```
perf:
```
,
```
test:
```
→ No version bump (by default)

```
feat:
```
→ 次版本号（MINOR）更新（0.1.0 → 0.2.0）
```
fix:
```
→ 修订版本号（PATCH）更新（0.1.0 → 0.1.1）
```
BREAKING CHANGE:
```
或
```
feat!:
```
→ 主版本号（MAJOR）更新（0.1.0 → 1.0.0）
```
docs:
```
、
```
chore:
```
、
```
style:
```
、
```
refactor:
```
、
```
perf:
```
、
```
test:
```
→ 默认不更新版本号

Release Notes Visibility (Important)

发布说明可见性（重要）

Warning: The

@semantic-release/release-notes-generator

(Angular preset) only includes these types in release notes:

```
feat:
```
→ Features section
```
fix:
```
→ Bug Fixes section
```
perf:
```
→ Performance Improvements section

Other types (

docs:

chore:

refactor:

, etc.) trigger releases when configured but do NOT appear in release notes.

Recommendation: For documentation changes that should be visible in release notes, use:

fix(docs): description of documentation improvement

This ensures the commit appears in the "Bug Fixes" section while still being semantically accurate (fixing documentation gaps is a fix).

注意：

@semantic-release/release-notes-generator

（Angular预设）仅在发布说明中包含以下类型的提交：

```
feat:
```
→ 功能特性章节
```
fix:
```
→ Bug修复章节
```
perf:
```
→ 性能优化章节

其他类型（

docs:

、

chore:

、

refactor:

等）在配置后可触发发布，但不会出现在发布说明中。

建议：若需让文档变更出现在发布说明中，使用：

fix(docs): 文档改进说明

这样既能确保提交出现在“Bug修复”章节，同时在语义上也是准确的（修复文档漏洞属于修复类变更）。

Marketplace Plugin Configuration (Always Bump)

市场插件配置（强制版本更新）

For Claude Code marketplace plugins, every change requires a version bump for users to receive updates.

Option A: Shareable Config (if published)

yaml

undefined

对于Claude Code市场插件，任何变更都需要更新版本号，以便用户收到更新。

选项A：可共享配置（已发布的情况）

yaml

undefined

.releaserc.yml

extends: "@terryli/semantic-release-config/marketplace"


**Option B: Inline Configuration**

```yaml

extends: "@terryli/semantic-release-config/marketplace"


**选项B：内联配置**

```yaml

.releaserc.yml

plugins:

- "@semantic-release/commit-analyzer"
- releaseRules:
  Marketplace plugins require version bump for ANY change
  - { type: "docs", release: "patch" }
  - { type: "chore", release: "patch" }
  - { type: "style", release: "patch" }
  - { type: "refactor", release: "patch" }
  - { type: "test", release: "patch" }
  - { type: "build", release: "patch" }
  - { type: "ci", release: "patch" }


**Result after configuration:**

| Commit Type                                                        | Release Type       |
| ------------------------------------------------------------------ | ------------------ |
| `feat:`                                                            | minor (default)    |
| `fix:`, `perf:`, `revert:`                                         | patch (default)    |
| `docs:`, `chore:`, `style:`, `refactor:`, `test:`, `build:`, `ci:` | patch (configured) |

**Why marketplace plugins need this**: Plugin updates are distributed via version tags. Without a version bump, users running `/plugin update` see no changes even if content was modified.

plugins:

- "@semantic-release/commit-analyzer"
- releaseRules:
  市场插件要求任何变更都需更新版本号
  - { type: "docs", release: "patch" }
  - { type: "chore", release: "patch" }
  - { type: "style", release: "patch" }
  - { type: "refactor", release: "patch" }
  - { type: "test", release: "patch" }
  - { type: "build", release: "patch" }
  - { type: "ci", release: "patch" }


**配置后的效果：**

| 提交类型                                                        | 发布类型       |
| ------------------------------------------------------------------ | ------------------ |
| `feat:`                                                            | 次版本号（默认）    |
| `fix:`、`perf:`、`revert:`                                         | 修订版本号（默认）    |
| `docs:`、`chore:`、`style:`、`refactor:`、`test:`、`build:`、`ci:` | 修订版本号（配置后） |

**为何市场插件需要此配置**：插件更新通过版本标签分发。若不更新版本号，用户执行`/plugin update`时，即使内容已修改也看不到任何变更。

MANDATORY: Every Release Must Increment Version

强制要求：每次发布必须递增版本号

Pre-release validation: Before running semantic-release, verify releasable commits exist since last tag. A release without version increment is invalid.

Autonomous check sequence:

List commits since last tag: compare HEAD against latest version tag
Identify commit types: scan for
```
feat:
```
,
```
fix:
```
, or
```
BREAKING CHANGE:
```
prefixes
If NO releasable commits found → STOP - do not proceed with release
Inform user: "No version-bumping commits since last release. Use
```
feat:
```
or
```
fix:
```
prefix for releasable changes."

Commit type selection guidance:

Use
```
fix:
```
for any change that improves existing behavior (bug fixes, enhancements, documentation corrections that affect usage)
Use
```
feat:
```
for new capabilities or significant additions
Reserve
```
chore:
```
,
```
docs:
```
,
```
refactor:
```
for changes that truly don't warrant a release

Why this matters: A release without version increment creates confusion - users cannot distinguish between releases, package managers may cache old versions, and changelog entries become meaningless.

发布前验证：运行semantic-release前，需验证自上次标签以来是否存在可触发发布的提交。未递增版本号的发布是无效的。

自动检查流程：

列出自上次标签以来的提交：将HEAD与最新版本标签进行对比
识别提交类型：扫描
```
feat:
```
、
```
fix:
```
或
```
BREAKING CHANGE:
```
前缀
若未找到可触发发布的提交 → 终止 - 不继续发布流程
告知用户：“自上次发布以来，没有可触发版本更新的提交。请使用
```
feat:
```
或
```
fix:
```
前缀标记可发布的变更。”

提交类型选择指南：

使用
```
fix:
```
标记任何改进现有行为的变更（Bug修复、功能增强、影响使用的文档修正）
使用
```
feat:
```
标记新功能或重大新增内容
仅当变更确实无需发布时，才使用
```
chore:
```
、
```
docs:
```
、
```
refactor:
```

重要性：未递增版本号的发布会造成混淆 - 用户无法区分不同版本，包管理器可能缓存旧版本，变更日志条目也会失去意义。

MAJOR Version Breaking Change Confirmation

主版本号（MAJOR）变更确认流程

Trigger:

BREAKING CHANGE:

footer or

feat!:

fix!:

prefix in commits.

When MAJOR is detected, this skill runs a 3-phase confirmation workflow:

Detection: Scan commits for breaking change markers
Analysis: Spawn 3 parallel subagents (User Impact, API Compat, Migration)
Confirmation: AskUserQuestion with proceed/downgrade/abort options

See MAJOR Confirmation Workflow for complete details including subagent prompts, decision tree, and example output.

触发条件：提交中包含

BREAKING CHANGE:

脚注或

feat!:

fix!:

前缀。

检测到主版本号变更时，本技能会运行3阶段确认工作流：

检测：扫描提交中的重大变更标记
分析：启动3个并行子代理（用户影响、API兼容性、迁移方案）
确认：向用户询问继续/降级/终止选项

完整详情包括子代理提示、决策树和示例输出，请参见主版本号确认工作流。

Examples

示例

Feature (MINOR):

feat: add BigQuery data source support

Bug Fix (PATCH):

fix: correct timestamp parsing for UTC offsets

Breaking Change (MAJOR):

feat!: change API to require authentication

BREAKING CHANGE: All API calls now require API key in Authorization header.

功能特性（次版本号）：

feat: 新增BigQuery数据源支持

Bug修复（修订版本号）：

fix: 修正UTC偏移量的时间戳解析问题

重大变更（主版本号）：

feat!: 修改API以要求身份验证

BREAKING CHANGE: 所有API调用现在需要在Authorization头中包含API密钥。

Documentation Linking

文档链接

Auto-include doc changes in release notes. Add to

.releaserc.yml

yaml

- - "@semantic-release/exec"
  - generateNotesCmd: "node plugins/itp/skills/semantic-release/scripts/generate-doc-notes.mjs ${lastRelease.gitTag}"

Detects: ADRs, Design Specs, Skills, Plugin READMEs. See Doc Release Linking.

Note: The
@semantic-release/exec
plugin uses Lodash templates (
${var}
). This conflicts with bash default syntax (
${VAR:-default}
) and subshell syntax (
$(cmd)
). Preferred fix: remove
successCmd
entirely if your task runner already handles post-release steps. See Troubleshooting: Lodash Template Conflicts.

自动在发布说明中包含文档变更。添加至

.releaserc.yml

：

yaml

- - "@semantic-release/exec"
  - generateNotesCmd: "node plugins/itp/skills/semantic-release/scripts/generate-doc-notes.mjs ${lastRelease.gitTag}"

可检测：ADR、设计规范、技能文档、插件README。详情请参见文档发布链接。

注意：
@semantic-release/exec
插件使用Lodash模板（
${var}
）。这与bash默认语法（
${VAR:-default}
）和子shell语法（
$(cmd)
）冲突。首选解决方案：若任务运行器已处理发布后步骤，完全移除
successCmd
。详情请参见排查：Lodash模板冲突。

Quick Start

快速开始

Prerequisites

前置条件

Check	Command	Fix
gh CLI authenticated	`gh auth status`	`gh auth login`
GH_TOKEN for directory	`gh api user --jq '.login'`	See Authentication
Git remote is HTTPS	`git remote get-url origin`	`git-ssh-to-https`
semantic-release global	`command -v semantic-release`	See Troubleshooting

检查项	命令	修复方案
gh CLI已认证	`gh auth status`	`gh auth login`
目录已配置GH_TOKEN	`gh api user --jq '.login'`	参见认证文档
Git远程仓库为HTTPS	`git remote get-url origin`	`git-ssh-to-https`
已全局安装semantic-release	`command -v semantic-release`	参见排查文档

Initialize Project

初始化项目

bash

./scripts/init-project.mjs --project   # Initialize current project
./scripts/init-project.mjs --user      # Create user-level shareable config
./scripts/init-project.mjs --help      # See all options

bash

./scripts/init-project.mjs --project   # 初始化当前项目
./scripts/init-project.mjs --user      # 创建用户级可共享配置
./scripts/init-project.mjs --help      # 查看所有选项

Run Release

运行发布

Priority	Condition	Commands
1	`.mise.toml` has release tasks	`mise run release:version` / `mise run release:full`
2	`package.json` has scripts	`npm run release:dry` (preview) / `npm run release`
3	Global CLI	`semantic-release --no-ci`

See Local Release Workflow for the complete 4-phase process.

优先级	条件	命令
1	`.mise.toml` 包含发布任务	`mise run release:version` / `mise run release:full`
2	`package.json` 包含脚本	`npm run release:dry` （预览） / `npm run release`
3	全局CLI工具	`semantic-release --no-ci`

完整的4阶段流程请参见本地发布工作流。

Python Projects

Python项目

semantic-release handles versioning. For PyPI publishing, see

pypi-doppler

skill.

Version pattern (importlib.metadata - never hardcode):

python

from importlib.metadata import PackageNotFoundError, version
try:
    __version__ = version("your-package-name")
except PackageNotFoundError:
    __version__ = "0.0.0+dev"

See Python Projects Guide for complete setup including Rust+Python hybrids.

semantic-release负责版本控制。PyPI发布请参见

pypi-doppler

技能。

版本号模式（使用importlib.metadata - 绝不硬编码）：

python

from importlib.metadata import PackageNotFoundError, version
try:
    __version__ = version("your-package-name")
except PackageNotFoundError:
    __version__ = "0.0.0+dev"

完整设置包括Rust+Python混合项目，请参见 Python项目指南。

GitHub Actions (Optional)

GitHub Actions（可选）

Not recommended as primary (2-5 minute delay). Repository Settings → Actions → Workflow permissions → Enable "Read and write permissions".

不推荐作为主要方式（延迟2-5分钟）。仓库设置 → Actions → 工作流权限 → 启用“读取和写入权限”。

Reference Documentation

参考文档

Category	Reference	Description
Setup	Authentication	HTTPS-first setup, multi-account patterns
Workflow	Local Release Workflow	4-phase process (PREFLIGHT → RELEASE → POSTFLIGHT)
Languages	Python Projects	Python + Rust+Python hybrid patterns
	Rust Projects	release-plz, cargo-rdme README SSoT
Config	Version Alignment	Git tags as SSoT, manifest patterns
	Monorepo Support	Polyglot monorepo with Pants + mise, pnpm/npm workspaces
Advanced	MAJOR Confirmation	Breaking change analysis workflow
	Doc Release Linking	Auto-link ADRs/specs in release notes
Help	Troubleshooting	All common issues consolidated
	Evolution Log	Skill change history

Cross-skill references:

```
mise-tasks
```
skill: polyglot-affected
- Complete Pants + mise integration guide
```
mise-tasks
```
skill: bootstrap-monorepo
- Autonomous polyglot monorepo setup
```
pypi-doppler
```
skill
- Local PyPI publishing with Doppler

分类	参考文档	描述
设置	认证	HTTPS优先设置、多账号模式
工作流	本地发布工作流	4阶段流程（预检 → 发布 → 发布后）
语言支持	Python项目	Python + Rust+Python混合项目模式
	Rust项目	release-plz、cargo-rdme README单一数据源
配置	版本对齐	Git标签作为单一数据源、清单模式
	单仓库支持	多语言单仓库结合Pants + mise、pnpm/npm工作区
高级功能	主版本号确认	重大变更分析工作流
	文档发布链接	自动在发布说明中链接ADR/规范文档
帮助	排查指南	所有常见问题汇总
	演进日志	技能变更历史

跨技能参考：

```
mise-tasks
```
技能: polyglot-affected
- Pants + mise完整集成指南
```
mise-tasks
```
技能: bootstrap-monorepo
- 自动多语言单仓库设置
```
pypi-doppler
```
技能
- 使用Doppler进行本地PyPI发布

Post-Change Checklist

变更后检查清单

After modifying THIS skill (semantic-release):

SKILL.md and references remain aligned
New references documented in Reference Documentation table
All referenced files in references/ exist
Append changes to evolution-log.md
Validate with
```
bun scripts/validate-plugins.mjs
```
Run
```
npm run release:dry
```
to verify no regressions

修改本技能（semantic-release）后：

SKILL.md与参考文档保持一致
新参考文档已添加至参考文档表
references/目录下所有引用文件均存在
将变更追加至 evolution-log.md
使用
```
bun scripts/validate-plugins.mjs
```
验证
运行
```
npm run release:dry
```
验证无回归问题

Troubleshooting

排查指南

Issue	Cause	Solution
No release created	No releasable commits since tag	Use `feat:` or `fix:` prefix for version-bumping commits
Wrong version bump	Commit type mismatch	Check conventional commit format and releaseRules
GitHub release not created	Missing GH_TOKEN or permissions	Check token is set and has repo scope
CHANGELOG not updated	Missing changelog plugin	Add `@semantic-release/changelog` to plugins array
"Authentication failed"	HTTPS vs SSH remote mismatch	Convert to HTTPS: `git-ssh-to-https`
semantic-release not found	Not installed globally	`npm install -g semantic-release`
Gatekeeper blocks on macOS	Unsigned Node files	See Troubleshooting
dry-run shows no changes	Already released at HEAD	Make new commits before running release
Multi-account token conflict	Wrong GH_TOKEN for directory	Configure mise [env] per-directory token

问题	原因	解决方案
未创建发布	自上次标签以来无可发布提交	使用 `feat:` 或 `fix:` 前缀标记可触发版本更新的提交
版本号更新错误	提交类型不匹配	检查约定式提交格式和releaseRules配置
未创建GitHub发布	缺少GH_TOKEN或权限不足	检查令牌已设置且拥有repo权限
CHANGELOG未更新	缺少changelog插件	在plugins数组中添加 `@semantic-release/changelog`
"认证失败"	HTTPS与SSH远程仓库不匹配	转换为HTTPS： `git-ssh-to-https`
找不到semantic-release	未全局安装	`npm install -g semantic-release`
macOS下Gatekeeper拦截	Node文件未签名	参见排查指南
预演无变更	HEAD已发布过	运行发布前先创建新提交
多账号令牌冲突	目录使用了错误的GH_TOKEN	配置mise [env]为每个目录设置独立令牌

semantic-release

Original

Translation

semantic-release

semantic-release

Overview

概述

When to Use This Skill

适用场景

Why Node.js semantic-release

为何选择Node.js版semantic-release

Release Workflow Philosophy: Local-First

发布工作流理念：本地优先

Why Local Releases

为何选择本地发布

GitHub Actions: Optional Backup Only

GitHub Actions：仅作为可选备用方案

Authentication Setup

认证设置

Browser authentication once

仅需一次浏览器认证

Credentials stored in keyring

凭据存储在密钥环中

All future releases: zero manual intervention

后续所有发布：无需手动干预

Multi-Account Authentication via mise [env]

通过mise [env]实现多账号认证

~/your-project/.mise.toml

~/your-project/.mise.toml

mise Task Detection

mise任务检测

GitHub Actions Policy

GitHub Actions 策略

Separation of Concerns (4-Level Architecture)

关注点分离（4层架构）

Configuration Precedence

配置优先级

Conventional Commits Format

约定式提交格式

Version Bump Rules (Default)

默认版本号更新规则

Release Notes Visibility (Important)

发布说明可见性（重要）

Marketplace Plugin Configuration (Always Bump)

市场插件配置（强制版本更新）

.releaserc.yml

.releaserc.yml

.releaserc.yml

.releaserc.yml

Marketplace plugins require version bump for ANY change

市场插件要求任何变更都需更新版本号

MANDATORY: Every Release Must Increment Version

强制要求：每次发布必须递增版本号

MAJOR Version Breaking Change Confirmation

主版本号（MAJOR）变更确认流程

Examples

示例

Documentation Linking

文档链接

Quick Start

快速开始

Prerequisites

前置条件

Initialize Project

初始化项目

Run Release

运行发布

Python Projects

Python项目

GitHub Actions (Optional)

GitHub Actions（可选）

Reference Documentation

参考文档

Post-Change Checklist

变更后检查清单

Troubleshooting

排查指南