GitHub Actions 手动触发工作流的页面路径

GitHub Actions 手动触发不是在仓库设置里随便找一个按钮，而是沿着“仓库首页 → Actions → 工作流名称 → Run workflow”进入运行面板。页面能否出现这个按钮，先取决于工作流是否声明了 workflow_dispatch，并且这份工作流文件已经存在于默认分支；执行手动运行还需要仓库写权限。

官方地址：https://github.com/

官方说明：https://docs.github.com/en/actions/how-tos/manage-workflow-runs/manually-run-a-workflow

下面用一个最小场景说明页面路径。配图是根据操作状态绘制的原创界面说明图，不是 GitHub 截图，也不是实际运行证据。

先确认 workflow_dispatch 与默认分支条件

先打开仓库中的 .github/workflows 目录，找到要手动执行的 YAML 文件。触发器至少要包含 workflow_dispatch；如果只写了 push 或 pull_request，Actions 页面不会出现手动运行入口。

name: 手动构建示例

on:
  workflow_dispatch:
    inputs:
      target:
        description: "要构建的目标"
        required: true
        default: "staging"
        type: choice
        options:
          - staging
          - production

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: 检出代码
        uses: actions/checkout@v4 # 这里保留中文注释，说明步骤用途
      - name: 输出目标
        run: echo "target=\${{ inputs.target }}" # 用输入值决定本次运行目标

这里的关键不是把 YAML 写得复杂，而是确认它已经提交到默认分支。GitHub 文档明确说明，手动触发要求工作流文件位于默认分支；只有满足这个前置条件，网页端的运行入口才有机会出现。

从仓库首页进入 Actions 和目标工作流

页面操作按下面的顺序进行：先进入目标仓库的主页面，在仓库名称下方点击 Actions；再在左侧工作流列表点击目标工作流名称。不要直接把某次运行记录当成工作流入口，手动触发按钮位于工作流自己的运行列表页面上方。

如果需要用路径表达这个页面，它可以抽象成：

https://github.com/OWNER/REPOSITORY/actions/workflows/WORKFLOW_FILE
# OWNER、REPOSITORY 和 WORKFLOW_FILE 需要替换成当前仓库的实际值

进入后先看工作流标题和最近运行记录，再找运行列表上方的 Run workflow。没有这个按钮时，优先回到上一节检查触发器和默认分支，不要先改浏览器或反复刷新。

选择分支并填写 workflow_dispatch 输入

点击 Run workflow 后，面板通常会给出 Branch 下拉框；如果 YAML 定义了 inputs，还会出现对应的输入字段。先选本次要运行的分支或标签，再按字段的必填要求填写参数，最后准备点击按钮。

上例中的 target 是必填的选择项，因此页面应该显示 staging 与 production 两个可选值。字段名称、默认值和可选项都来自工作流文件，不是页面临时生成的固定菜单。

点击 Run workflow 并判断页面结果

确认分支和输入后点击 Run workflow。正常情况下，页面会返回工作流运行列表，并在列表中出现一条新的运行记录；之后可以打开这条记录查看 job 和 step 的状态。这里判断“手动触发成功”的标准是新的运行记录出现，而不是只看到按钮被点击。

命令行也可以触发同一类工作流，但它不是本篇的页面路径：

gh workflow run build.yml --ref main
# --ref 指定要运行的分支；工作流仍需声明 workflow_dispatch

遇到异常时按这个顺序排查：

• 没有 Run workflow：检查默认分支上的 YAML 是否含有 workflow_dispatch，并确认最近的提交已经推送。
• 按钮可见但无法执行：确认当前账号对仓库有写权限，以及所选分支或标签存在。
• 输入字段不符合预期：回到 on.workflow_dispatch.inputs 查看字段名、是否必填、默认值和类型。
• 运行列表没有新记录：先确认点击的是工作流页面里的按钮，再检查页面是否已经切换到目标仓库和目标工作流。

相关问题

为什么 workflow_dispatch 写了却没有按钮？最常见原因是包含该配置的文件还不在默认分支，或者当前打开的不是那份工作流对应的运行列表。

手动触发一定只能运行默认分支吗？网页面板可以选择分支；限制是用于提供手动触发入口的工作流文件需要先存在于默认分支。

没有 inputs 时还能手动运行吗？可以。inputs 只是让页面展示额外参数字段，手动触发的核心前置条件仍是 workflow_dispatch。