name

github-actions-release

description

Execute and troubleshoot GitHub Actions releases for this monorepo, including pnpm setup, multi-platform Electron packaging, tag replacement, artifact publication, and post-release verification. Use when a user asks to trigger, rerun, repair, or verify a GitHub Actions release, especially when pnpm/action-setup, setup-node caching, release tags, unsigned bundled/slim artifacts, or the Publish GitHub Release job is involved.

GitHub Actions Release

按“配置检查 → 本地轻量验证 → 提交与 tag → 观察 Actions → 验证 Release”执行发布。先检查仓库当前状态和 workflow，再决定是否需要修改；不要因为 CI 失败直接删除根目录 packageManager。

1. 固定包管理器安装路径

本仓库的版本真值是根 package.json 的：

"packageManager": "pnpm@11.12.0"

turbo 依赖这个字段解析 workspace。CI 使用 Node 22，并按以下顺序安装 pnpm：

- name: Set up Node.js
  uses: actions/setup-node@v5
  with:
    node-version: 22
    package-manager-cache: false

- name: Set up pnpm
  run: npm install --global pnpm@11.12.0

随后显式执行 pnpm --version 和版本校验。package-manager-cache: false 必须保留：setup-node 会读取根 packageManager 并在 pnpm 尚未安装时自动尝试缓存，导致 Unable to locate executable file: pnpm。

pnpm/action-setup 的已知故障

遇到以下错误时，先移除 pnpm/action-setup，不要继续尝试删掉 packageManager：

Cannot use 'in' operator to search for 'integrity' in undefined
action 从 bootstrap 版本切换到 11.12.0 时失败
standalone: true 后出现 This: not found 或 @pnpm/exe 无效
Windows runner 无法执行 self-installer 生成的 pnpm

固定 pnpm/action-setup@v6.0.8 仍可能失败，因为 action 会先自举一个 pnpm，再执行 self-update。standalone: true 又可能让 setup-node 缓存到损坏的可执行文件。当前验证通过的方案是 Node 先安装，再用 npm 全局安装目标 pnpm，并关闭 setup-node 自动缓存。

2. 发布 workflow 检查

修改前检查：

git status --short
git branch --show-current
sed -n '1,260p' .github/workflows/release.yml
sed -n '1,220p' .github/workflows/pages.yml

确认以下约束仍成立：

tag 校验读取 apps/desktop/package.json 的版本。
矩阵只包含 macOS arm64、Windows x64、Linux x64。
每个平台同时生成 bundled-ffmpeg 和 slim，artifact 名称必须区分两者。
Electron 构建从桌面包上下文执行：pnpm --filter video-translate run build:ci。
Linux target 只保留项目要求的格式；不要让额外平台或 .blockmap 混入发布资产。
Pages workflow 与 release workflow 使用同一套可验证的 pnpm 安装策略（Node 后 npm i -g pnpm@11.12.0，package-manager-cache: false）。Pages 额外在装好 pnpm 后用 actions/cache@v4 缓存 pnpm store path（按 pnpm-lock.yaml 哈希），不缓存 node_modules、不启用 setup-node 自动 cache。
Publish 步骤每次都会跑 scripts/organize-release-notes.mjs，把 scripts/release-notes-preamble.md（精简的 bundled/slim 对照 + 非签名要点 + 官网文档链接）固定写到 Release 正文顶部，并与 ## What's Changed 变更分组共存；完整安装说明在 landing /docs，修改包说明时改该 md 即可。

轻量验证优先于完整原生构建：

pnpm exec vitest run tests/release-workflow.test.mjs tests/package-manager-config.test.mjs
pnpm exec oxfmt --check package.json apps/desktop/package.json apps/landing/package.json apps/landing/src/App.tsx README.md .github/workflows/release.yml
git diff --check

测试应验证真实版本、安装命令、缓存开关、构建脚本和 artifact 规则；不要只断言字段存在。

3. 提交、tag 和重发

用户只要求触发已存在版本时，先确认是否允许替换远端 tag。只有得到明确确认后，才执行删除并重建；不使用 force push：

git tag -d vX.Y.Z
git push origin :refs/tags/vX.Y.Z
git tag -a vX.Y.Z -m "发布 vX.Y.Z"
git push origin HEAD
git push origin vX.Y.Z

版本变更使用中文 Conventional Commit，例如：

chore(release): 发布 v0.4.1

若 tag、commit 或 push 失败，保留现场并报告失败点，不自动重复覆盖。

4. 观察 Actions

触发后记录运行 ID 和 URL：

gh run list --workflow release.yml --limit 5
gh run watch RUN_ID --exit-status
gh run view RUN_ID --json status,conclusion,jobs

按阶段判断：

Set up Node.js 失败：检查 package-manager-cache: false 是否存在。
Set up pnpm 失败：确认没有残留 pnpm/action-setup，并查看 npm 全局安装输出。
Verify release version 失败：比较 tag、apps/desktop/package.json 和 workflow 读取路径。
依赖安装失败：先确认 pnpm 版本，再区分 registry、原生依赖和 workflow 配置问题。
构建步骤持续较久：以 job 状态和最终日志为准，不因等待时间长提前重跑；bundled Linux/Windows 构建可能明显慢于 slim。
Publish GitHub Release 必须完成后，才报告发布完成；矩阵构建成功不等于 Release 已创建。

如果 GitHub API 触发 rate limit，改用公开 Actions 页面和 Release 页面确认，不要连续高频轮询 API。

5. 发布后验证

验证远端分支、tag 和实际 Release：

git rev-parse HEAD
git ls-remote origin refs/heads/main 'refs/tags/vX.Y.Z^{}'

只有两者都指向本次提交，并且 Release 页面显示目标 tag、六个构建产物（或当前矩阵约定的完整数量）及 checksum，才报告完成。若页面仍显示旧状态，重新打开页面确认；不要仅凭一次 API 响应下结论。

失败模式速查

现象	根因	处理
`Could not resolve workspace`	根 `packageManager` 缺失	恢复并固定 `pnpm@11.12.0`
self-installer 的 `integrity` 错误	action 自举版本切换失败	改为 Node 后 `npm install --global`
standalone 生成 `This: not found`	`@pnpm/exe` 下载或缓存异常	移除 standalone，并关闭自动缓存
setup-node 找不到 pnpm	自动缓存早于 pnpm 安装	设置 `package-manager-cache: false`
`electron-builder: command not found`	从错误 workspace 上下文直接调用	使用桌面包的 `build:ci` 脚本
Release 没有资产	只完成了矩阵 job	等待并检查 `Publish GitHub Release`

name

github-actions-release

description

GitHub Actions Release

1. 固定包管理器安装路径

本仓库的版本真值是根 package.json 的：

"packageManager": "pnpm@11.12.0"

turbo 依赖这个字段解析 workspace。CI 使用 Node 22，并按以下顺序安装 pnpm：

- name: Set up Node.js
  uses: actions/setup-node@v5
  with:
    node-version: 22
    package-manager-cache: false

- name: Set up pnpm
  run: npm install --global pnpm@11.12.0

pnpm/action-setup 的已知故障

遇到以下错误时，先移除 pnpm/action-setup，不要继续尝试删掉 packageManager：

Cannot use 'in' operator to search for 'integrity' in undefined
action 从 bootstrap 版本切换到 11.12.0 时失败
standalone: true 后出现 This: not found 或 @pnpm/exe 无效
Windows runner 无法执行 self-installer 生成的 pnpm

2. 发布 workflow 检查

修改前检查：

git status --short
git branch --show-current
sed -n '1,260p' .github/workflows/release.yml
sed -n '1,220p' .github/workflows/pages.yml

确认以下约束仍成立：

tag 校验读取 apps/desktop/package.json 的版本。
矩阵只包含 macOS arm64、Windows x64、Linux x64。
每个平台同时生成 bundled-ffmpeg 和 slim，artifact 名称必须区分两者。
Electron 构建从桌面包上下文执行：pnpm --filter video-translate run build:ci。
Linux target 只保留项目要求的格式；不要让额外平台或 .blockmap 混入发布资产。
Pages workflow 与 release workflow 使用同一套可验证的 pnpm 安装策略（Node 后 npm i -g pnpm@11.12.0，package-manager-cache: false）。Pages 额外在装好 pnpm 后用 actions/cache@v4 缓存 pnpm store path（按 pnpm-lock.yaml 哈希），不缓存 node_modules、不启用 setup-node 自动 cache。
Publish 步骤每次都会跑 scripts/organize-release-notes.mjs，把 scripts/release-notes-preamble.md（精简的 bundled/slim 对照 + 非签名要点 + 官网文档链接）固定写到 Release 正文顶部，并与 ## What's Changed 变更分组共存；完整安装说明在 landing /docs，修改包说明时改该 md 即可。

轻量验证优先于完整原生构建：

pnpm exec vitest run tests/release-workflow.test.mjs tests/package-manager-config.test.mjs
pnpm exec oxfmt --check package.json apps/desktop/package.json apps/landing/package.json apps/landing/src/App.tsx README.md .github/workflows/release.yml
git diff --check

测试应验证真实版本、安装命令、缓存开关、构建脚本和 artifact 规则；不要只断言字段存在。

3. 提交、tag 和重发

用户只要求触发已存在版本时，先确认是否允许替换远端 tag。只有得到明确确认后，才执行删除并重建；不使用 force push：

git tag -d vX.Y.Z
git push origin :refs/tags/vX.Y.Z
git tag -a vX.Y.Z -m "发布 vX.Y.Z"
git push origin HEAD
git push origin vX.Y.Z

版本变更使用中文 Conventional Commit，例如：

chore(release): 发布 v0.4.1

若 tag、commit 或 push 失败，保留现场并报告失败点，不自动重复覆盖。

4. 观察 Actions

触发后记录运行 ID 和 URL：

gh run list --workflow release.yml --limit 5
gh run watch RUN_ID --exit-status
gh run view RUN_ID --json status,conclusion,jobs

按阶段判断：

Set up Node.js 失败：检查 package-manager-cache: false 是否存在。
Set up pnpm 失败：确认没有残留 pnpm/action-setup，并查看 npm 全局安装输出。
Verify release version 失败：比较 tag、apps/desktop/package.json 和 workflow 读取路径。
依赖安装失败：先确认 pnpm 版本，再区分 registry、原生依赖和 workflow 配置问题。
构建步骤持续较久：以 job 状态和最终日志为准，不因等待时间长提前重跑；bundled Linux/Windows 构建可能明显慢于 slim。
Publish GitHub Release 必须完成后，才报告发布完成；矩阵构建成功不等于 Release 已创建。

如果 GitHub API 触发 rate limit，改用公开 Actions 页面和 Release 页面确认，不要连续高频轮询 API。

5. 发布后验证

验证远端分支、tag 和实际 Release：

git rev-parse HEAD
git ls-remote origin refs/heads/main 'refs/tags/vX.Y.Z^{}'

失败模式速查

现象	根因	处理
`Could not resolve workspace`	根 `packageManager` 缺失	恢复并固定 `pnpm@11.12.0`
self-installer 的 `integrity` 错误	action 自举版本切换失败	改为 Node 后 `npm install --global`
standalone 生成 `This: not found`	`@pnpm/exe` 下载或缓存异常	移除 standalone，并关闭自动缓存
setup-node 找不到 pnpm	自动缓存早于 pnpm 安装	设置 `package-manager-cache: false`
`electron-builder: command not found`	从错误 workspace 上下文直接调用	使用桌面包的 `build:ci` 脚本
Release 没有资产	只完成了矩阵 job	等待并检查 `Publish GitHub Release`

github-actions-release

GitHub Actions Release

1. 固定包管理器安装路径

pnpm/action-setup 的已知故障

2. 发布 workflow 检查

3. 提交、tag 和重发

4. 观察 Actions

5. 发布后验证

失败模式速查

More from this repository

More from this repository

GitHub Actions Release

1. 固定包管理器安装路径

pnpm/action-setup 的已知故障

2. 发布 workflow 检查

3. 提交、tag 和重发

4. 观察 Actions

5. 发布后验证

失败模式速查