[!info] related notes

• 前置笔记: github-actions
• 相关 MOC: ci-cd-moc

GitHub Actions 手动触发 workflow

目标

手动触发声明了 workflow_dispatch 的工作流。下面以补充已有 release 的二进制文件为例；是否修改版本、tag 或 changelog，完全取决于被触发的 workflow 内容。

适用场景

• 已有 release/tag（如 v0.1.0），但缺少二进制文件
• 需要为现有 release 补充构建产物
• 避免手动创建新 tag 导致 release-please 版本基线混乱

前置检查

• 当前账户具有所需仓库权限，默认分支上的目标工作流声明了 workflow_dispatch。
• 确认文件名、输入参数和目标 ref；Release Assets、release.yml 是原笔记中的示例名称，不代表每个仓库都有这些配置。
• 若用于补资产，检查 workflow 确实按输入 tag checkout，并上传到已有 release；查看它是否还会创建版本、覆盖资产或执行其他发布步骤。

步骤

1. 通过 GitHub 网页界面触发

1. 打开仓库的 Actions 页面
2. 在左侧找到实际负责该任务的 workflow（例如 Release Assets）
3. 点击右上角 Run workflow 按钮
4. 在弹出的表单中：
   • tag：输入已存在的 tag（如 v0.1.0）
   • branch：选择 main 或其他目标分支
5. 点击 Run workflow 确认

2. 通过命令行触发（使用 gh CLI）

gh workflow run release.yml --ref main -f tag=v0.1.0

关键点

• tag 输入的是”已存在的 Git tag”，不是新建 tag
• --ref main 选择运行工作流的 ref；-f tag=... 只是传入名为 tag 的输入，两者不等价。只有 workflow 将输入用于 checkout 和上传时，才会构建该 tag 并补充同名 release
• 要保证不改变 release-please 状态，必须检查工作流只做目标操作；workflow_dispatch 触发器自身不提供这个保证

验证

触发成功后，检查：

1. Actions 页面：workflow 是否正在运行或已完成
2. Release 页面：现有 release（如 v0.1.0）是否新增了二进制文件
3. 预期产物：
   • Windows: *Setup.exe, *Setup.zip
   • Linux: *.AppImage, *.deb, *.rpm

常见问题

Q1: Actions 页面没有 Run workflow 按钮？

可能原因：

• 没有仓库写权限
• 默认分支上还没有包含 workflow_dispatch 触发器
• 打开的不是正确的 workflow

Q2: 为什么不能手动创建新 tag？

• release-please 靠”上一个 release tag”决定下一次版本和 changelog 基线
• 手动创建 semver tag（尤其是落在 main 上的新版本 tag）可能打乱 release-please 的基线
• 导致后续版本或 changelog 计算异常

Q3: 什么时候可以手动创建 tag？

只在以下情况考虑：

• 一次性历史补录
• tag 格式必须与该项目的 release-please 配置一致；vX.Y.Z 只是常见形式，monorepo 等项目可能有组件前缀
• 必须指向正确的发布提交
• 确认不会和 release-please 下一次准备发的版本冲突

Q4: 补资产 vs 补版本的区别？

• 补资产：为已有 release 添加二进制文件 → 使用 workflow_dispatch 手动触发
• 补版本：创建新的 release/tag → 让 release-please 自动处理

配置示例（不是当前仓库状态声明）

• release-please 配置：release-please-config.json
• workflow 文件：.github/workflows/release.yml
• 确保 workflow 包含 workflow_dispatch 触发器：

on:
  workflow_dispatch:
    inputs:
      tag:
        description: 'Tag to build assets for'
        required: true
        type: string

Related notes

• Git MOC

参考资料

• GitHub：手动运行工作流