GitHub Actions 如何手动运行 workflow_dispatch 工作流：入口、分支与输入校验

流水线明明写了，GitHub Actions 页面却找不到 Run workflow；好不容易点到按钮，又发现任务跑在默认分支而不是刚修好的分支。这类问题通常不是 Actions 挂了，而是 workflow_dispatch 的入口、工作流文件所在分支和本次运行的 ref 没对齐。

先确认这次运行应该得到什么

假设仓库里有一个 browser-test.yml，它需要接收一个环境参数。一次合格的手动运行，至少要能回答四个问题：从哪个入口触发、实际使用了哪个分支、inputs 传了什么值、最终运行记录是否对应这次操作。

如果只看到一条普通的 push 记录，或者工作流列表里没有 Run workflow，先别反复刷新页面。先看 YAML 是否真的声明了手动事件：

name: Browser Tests

on:
  workflow_dispatch:
    inputs:
      target:
        description: "要检查的环境"
        required: true
        default: "staging"
        type: choice
        options:
          - staging
          - production

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - run: echo "target=${{ inputs.target }}"

这个文件必须已经位于仓库默认分支的 .github/workflows/ 目录。只把它提交在一个临时分支里，网页端可能仍然不会给默认工作流列表显示手动入口。

网页端入口在哪里，看到什么才算对

打开目标仓库主页，点顶部的 Actions 选项卡。仓库导航栏会直接把 Actions 作为独立入口展示，不用绕别的路径：

进入 Actions 后，在左侧选择具体工作流。若当前文件含有 workflow_dispatch，工作流页面会在运行列表上方显示 Run workflow 按钮；如果按钮不出现，优先检查工作流文件是否在默认分支、事件名称是否拼对，以及该文件是否已经提交。

点下运行按钮之后先选好要执行的 Branch，再按需填写输入项，最后提交运行。这里很多人容易踩坑：入口按钮能正常显示，不代表这次运行会自动沿用你当前浏览器里打开的分支，运行分支必须在弹出的操作面板里手动指定。

分支和输入参数怎么避免传错

网页操作适合偶尔手动触发，但正式排查时建议把选择写下来。比如这次要验证 release/2026-08，就把它作为运行分支；不要先在页面上打开某个分支，再默认认为按钮会继承它。

输入项要和 YAML 中的名字完全一致。示例里的字段是 target，不是 environment。运行后打开本次记录的日志，先搜索实际打印出的 target=，再判断测试是否命中了正确环境。

用 GitHub CLI 复现同一次手动运行

如果需要重复触发操作，或是要把手动运行逻辑集成到脚本里，可以直接用 GitHub CLI 来操作。下面的命令会明确指定要运行的工作流文件和目标分支，不用靠交互式选择就能直接执行：

gh workflow run browser-test.yml \
  --ref release/2026-08 \
  -f target=staging

如果 workflow 名称、数字 ID 或文件名都能唯一定位工作流，三者都可以作为第一个参数。参数传入后不要只看命令返回没有报错；继续用 gh run list 找到刚创建的运行，再用 gh run watch 跟踪它。

gh run list --workflow browser-test.yml --limit 5
gh run watch

需要传入的参数较多时，CLI 也支持直接传入 JSON 格式的输入。不管用哪种调用方式，都建议你在任务日志的开头位置打印非敏感的运行上下文信息，比如分支名、环境名和提交 SHA，绝对不要把 token、密码或者完整密钥直接输出到公开日志里。

结果核对要看哪几处

一次手动运行跑完之后，按下面的顺序核对结果效率更高：

• 运行详情里的工作流名称和触发事件，确认确实是手动触发的。
• Summary 区域或者运行元数据里记录的分支、提交 SHA，确认和你选的目标分支完全对应。
• 日志里打印的 target 是否与本次输入一致。
• 逐个检查关键任务是否全部执行成功，不要只看页面上的绿色成功标识就直接认定没问题。
• 如果任务会生成构建产物，下载后核对文件名、文件大小和校验值是否和预期一致。

网页端看不到按钮时，先回到默认分支检查文件；CLI 报工作流不存在时，先列出当前仓库能识别的工作流；任务跑错分支时，不要直接重跑旧记录，改正 --ref 后建立一条新的可追踪记录。

常见问题

为什么 Actions 页面没有 Run workflow？

最常见原因是工作流没有声明 workflow_dispatch，或者工作流文件还没有进入默认分支。先检查事件配置和提交位置，再刷新工作流页面。

网页端能不能运行非默认分支？

可以实现。点击 Run workflow 按钮之后，在 Branch 下拉列表里选中你要的目标分支就行，前提是这个工作流配置完全满足 GitHub 对手动触发入口的识别规则。

inputs 的默认值什么时候生效？

如果没有填写某个可选输入项，工作流定义里预先写好的默认值会自动生效。为了避免后续排查出错，建议在日志开头直接打印最终实际生效的所有输入项内容。

把手动发布变成可验收的操作

手动触发的关键不是“点到按钮”，而是让入口、分支、输入和结果形成一条可回看的链路。临时验证用网页端即可；需要重复执行时，把工作流文件名、--ref 和输入参数写进 CLI 命令，并在运行记录中核对 commit SHA 与日志结果，下一次排查就不会从猜测开始。