GitHub Actions workflow_dispatch 怎样添加手动输入参数

如果一个 GitHub Actions 工作流既要跑测试环境，又要跑预发布环境，最省事的做法不是复制两份 YAML，而是给手动触发事件加上输入字段。配置完成后，Actions 页面会出现 Run workflow 表单，命令行也可以用 gh workflow run 传值。

本文只解决一个问题：怎样为 workflow_dispatch 声明手动输入，并在 job 中读取这些值。官方地址：https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#workflow_dispatch。下面的两张图片是原创静态界面说明图，不是 GitHub 实际截图。

核心做法是在工作流文件的 on.workflow_dispatch.inputs 下声明字段，再通过 inputs. 在 job 或 step 中读取。先确认工作流文件位于默认分支，才能在网页上看到手动运行入口。

先确认手动触发入口

打开仓库的 .github/workflows/ 目录，选择要手动运行的工作流文件。最小配置只需要启用 workflow_dispatch：

name: Manual checks

on:
  # 启用 Actions 页面和 API/CLI 的手动触发入口
  workflow_dispatch:

jobs:
  show-entry:
    runs-on: ubuntu-latest
    steps:
      - name: Print entry state
        run: echo "manual workflow is available"

保存后把文件提交到默认分支。在仓库的 Actions 页面打开这条工作流，如果文件已经被默认分支识别，页面会出现 Run workflow 按钮。只有打开按钮还不够，继续配置输入字段后，按钮才会展开可填写的表单。

在 workflow_dispatch 下声明 inputs

输入字段写在 on.workflow_dispatch.inputs 下。下面的示例用三个字段覆盖常见场景：下拉选择日志级别、布尔开关和必填的部署环境。

name: Manual checks

on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: "本次运行使用的日志级别"
        required: true
        default: "warning"
        type: choice
        options:
          - info
          - warning
          - debug
      runIntegration:
        description: "是否执行集成测试"
        required: false
        default: false
        type: boolean
      environment:
        description: "选择要检查的环境"
        required: true
        type: environment

jobs:
  inspect-inputs:
    runs-on: ubuntu-latest
    steps:
      - name: Print selected values
        env:
          # 将上下文值显式放入环境变量，便于脚本读取
          LOG_LEVEL: ${{ inputs.logLevel }}
          RUN_INTEGRATION: ${{ inputs.runIntegration }}
          TARGET_ENV: ${{ inputs.environment }}
        run: |
          # 只回显本次运行的非敏感参数，不打印 Token 或密码
          echo "log level: $LOG_LEVEL"
          echo "run integration: $RUN_INTEGRATION"
          echo "target environment: $TARGET_ENV"

这里的 choice 只能从 options 中选择，boolean 用于开关，environment 则让调用者选择仓库中已有的环境。required 决定表单是否必须填写；default 只负责在表单中提供初始值，不等于业务逻辑已经执行。

在 job 和 step 中读取输入

声明输入只是提供数据，真正决定行为的是读取方式。条件表达式可以直接引用 inputs 上下文；命令脚本则建议先通过 env 显式接收，避免把表达式和 shell 语法混在一起。

jobs:
  test:
    # 布尔输入可直接控制 job 是否运行
    if: ${{ inputs.runIntegration }}
    runs-on: ubuntu-latest
    steps:
      - name: Run integration tests
        env:
          # 环境变量名使用大写，便于脚本与日志辨认
          TARGET_ENV: ${{ inputs.environment }}
        run: |
          # 这里的命令只示意测试入口，实际项目替换成自己的测试命令
          echo "testing environment: $TARGET_ENV"
          go test ./...

如果布尔值只用于条件判断，可以直接写 if: ${{ inputs.runIntegration }}。如果要交给 shell 或其他脚本，再放进 env 并按字符串使用。不要把用户输入拼接进未受控的 shell 命令；路径、参数和可执行选项应保持在明确的白名单内。

从 Run workflow 页面提交参数

回到 Actions 页面，选择目标工作流并点击 Run workflow。先选择要运行的分支，再按表单填写日志级别、集成测试开关和环境，最后提交。必填字段没有值时，页面不会创建本次运行。

提交后的可见成功状态是：运行记录出现在该工作流的列表中，进入详情后能看到对应 job；日志中可以看到非敏感输入的回显。不要把密码、访问令牌或完整部署凭据定义成普通输入并打印到日志。

用 GitHub CLI 传入同一组输入

同一工作流也可以用 GitHub CLI 触发。-f 后面的字段名必须与 YAML 中的输入名一致，布尔值和选择值都按表单允许的值传递：

# 指定工作流文件、分支，并传入与 YAML 同名的输入
gh workflow run manual-checks.yml \
  --ref main \
  -f logLevel=debug \
  -f runIntegration=true \
  -f environment=staging

# 查看最近的运行记录，确认手动触发已经进入队列
gh run list --workflow manual-checks.yml --limit 5

页面触发和 CLI 触发最终都进入同一个 workflow_dispatch 事件。CLI 的优点是可以嵌入脚本，但脚本仍应限制允许的分支、环境和选项，避免把任意输入直接传给部署命令。

输入不显示或读取为空时排查

1. 检查文件分支：确认工作流文件已经提交到默认分支；只在功能分支存在时，Actions 页面可能看不到手动入口。
2. 检查缩进层级：确认 inputs 位于 on.workflow_dispatch 下，而不是与 jobs 同级的自定义键。
3. 检查字段名：YAML 声明、inputs.、gh workflow run -f 三处必须使用同一个名称。
4. 检查上下文位置：job 条件使用 Actions 表达式；shell 脚本使用环境变量，不能把 ${{ inputs.name }} 当成 shell 变量。
5. 检查类型边界：choice 必须命中 options，environment 必须选择仓库可用环境；默认值只在没有新值时填入。

GitHub 文档还说明，inputs 上下文与 github.event.inputs 内容相同，但 inputs 会保留布尔值类型；实际写条件时优先使用 inputs，只有需要兼容旧写法时再查看事件上下文。

速查表

相关问题

为什么写了 workflow_dispatch 仍然没有 Run workflow？

先确认工作流文件在默认分支、路径位于 .github/workflows/，并且 YAML 的 on 与 workflow_dispatch 缩进正确。文件只在其他分支时，默认分支的 Actions 页面不会显示它。

inputs 和 github.event.inputs 应该选哪个？

新配置优先使用 inputs。两者值相同，但 inputs 会保留布尔值；事件上下文更适合需要读取原始事件结构的兼容场景。

能不能把密码也做成 workflow_dispatch 输入？

不建议。普通输入会出现在运行参数链路中，适合环境名、开关和日志级别；敏感值应放到 GitHub Secrets 或环境保护规则中，并避免在日志中回显。