GitHub Actions 手动运行工作流怎样传入参数

我第一次把部署工作流交给同事手动运行时，最容易出错的不是 YAML 缩进，而是“参数到底从哪里进来”。GitHub Actions 的做法是：在 workflow_dispatch 下声明 inputs，网页端的 Run workflow 表单会据此生成输入框；工作流运行后，再从 inputs 上下文读取值。

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

下面用一个手动部署场景说明版本号、目标环境和是否执行部署三个参数。配图是原创操作说明图，用来解释页面层级和字段关系，不是 GitHub 实际运行截图。

一、先把工作流改成可手动运行

先在仓库的工作流目录准备一个 YAML 文件，例如 .github/workflows/deploy.yml。触发器写成 workflow_dispatch 后，GitHub 才会为它提供手动运行入口；工作流文件还需要存在于默认分支，网页端才会显示 Run workflow。

name: Manual deploy

on:
  # 只有声明这个事件，Actions 页面才会提供手动运行入口
  workflow_dispatch:
    inputs:
      release_tag:
        description: "要部署的版本标签"
        required: true
        type: string
      target_env:
        description: "部署目标环境"
        required: true
        type: choice
        options:
          - staging
          - production
      perform_deploy:
        description: "是否真正执行部署"
        required: true
        default: false
        type: boolean

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      # 先打印非敏感参数，方便确认本次运行拿到的值
      - name: Show inputs
        run: |
          echo "tag=${{ inputs.release_tag }}"
          echo "environment=${{ inputs.target_env }}"
          echo "perform_deploy=${{ inputs.perform_deploy }}"

这里的 inputs 是输入定义区，不是 job 参数。required 控制是否必须填写，default 提供初始值，type 决定网页表单如何呈现。choice 适合固定环境，能减少手动输入拼写错误。

二、把输入字段和任务条件对齐

声明字段后，不要只在第一步 echo。真正的部署任务应当把输入用于环境选择、版本选择或条件判断。例如只有用户把 perform_deploy 设为 true 时，部署步骤才继续：

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Prepare release
        run: |
          # 用输入值组成当前任务的非敏感上下文
          echo "准备 ${{ inputs.release_tag }} -> ${{ inputs.target_env }}"

      - name: Deploy to target
        if: ${{ inputs.perform_deploy }}
        run: |
          # 真正的部署命令放在条件步骤中，避免误操作
          ./scripts/deploy.sh "${{ inputs.release_tag }}" "${{ inputs.target_env }}"

这一步的关键是让“表单字段”和“执行条件”一一对应：版本号进入部署脚本，环境值决定目标，布尔值只负责是否继续。不要把 Token 或密码当作普通输入展示，敏感信息应使用 GitHub Secrets。

三、网页端手动运行并填写参数

提交到默认分支后，打开仓库的 Actions，在左侧选择对应工作流，点击 Run workflow。先选择 Branch，再填写 Release tag、Target environment 和 Perform deploy，最后提交。

如果看不到 Run workflow，先排查三件事：文件是否位于默认分支、顶层事件是否确实是 workflow_dispatch、当前账号是否有运行工作流所需的写权限。不要先改 inputs 名称，因为入口缺失通常发生在触发器或分支位置。

四、也可以用 gh CLI 传入参数

熟悉命令行时，可以用 GitHub CLI 运行同一个工作流。-f 适合直接传入键值，工作流名可以写文件名；下面的命令仍然只传非敏感示例参数：

# -f 使用 key=value 传入 workflow_dispatch 的字段
gh workflow run deploy.yml \
  --ref main \
  -f release_tag=v2.4.0 \
  -f target_env=staging \
  -f perform_deploy=false

GitHub CLI 也支持交互式选择，或者用 JSON 标准输入一次传入多个字段。需要注意：CLI 的字段名必须和 YAML 中的 input ID 完全一致，--ref 只是选择运行分支，不会替代工作流输入。

常见问题

为什么网页端没有 Run workflow 按钮？

确认工作流文件在默认分支，并且顶层配置使用了 workflow_dispatch。另外还要确认账号具备运行工作流的权限。

inputs 和 github.event.inputs 有什么区别？

两者都能访问手动输入；官方文档说明 inputs 上下文会保留布尔值的布尔类型，而 github.event.inputs 中的值会转成字符串。条件判断优先使用 inputs.perform_deploy，更符合字段类型。

最多能声明多少个输入字段？

官方工作流语法对 workflow_dispatch 的顶层 inputs 数量和 payload 大小都有上限。字段较多时，应把稳定配置放进仓库文件或环境配置，不要把手动表单做成完整配置中心。

把流程记成四个动作就够了：默认分支提供入口，workflow_dispatch.inputs 定义表单，网页或 CLI 负责传值，任务从 inputs 上下文读取并做条件控制。这样手动运行既保留了人工选择，又不会让参数在工作流各处失去边界。