当前位置：首页 > 文章列表 > 文章 > 软件教程 > GitHub Actions 手动运行工作流怎样传入参数

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

来源：17golang原创 2026-10-14 10:15:41 0浏览收藏

我第一次把部署工作流交给同事手动运行时，最容易出错的不是 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 适合固定环境，能减少手动输入拼写错误。

原创 GitHub Actions 工作流编辑器说明图显示 workflow_dispatch 与 inputs 参数层级 — 图1：操作示意图，查看 workflow_dispatch 与 inputs 的层级关系，以及手动部署参数的声明位置。

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

声明字段后，不要只在第一步 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 名称，因为入口缺失通常发生在触发器或分支位置。

原创 GitHub Actions Run workflow 表单说明图显示分支与输入参数填写状态 — 图2：结果示意图，查看 Run workflow 表单中的分支、输入字段和提交前的参数摘要。

四、也可以用 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 只是选择运行分支，不会替代工作流输入。