CI/CD / 系统课时
用手动参数启动部署任务
用手动参数启动部署任务
自动部署并不适合所有场景。生产发布往往需要明确选择环境、版本或是否执行高风险步骤。GitHub Actions 的 workflow_dispatch 可以把这些选项定义为手动输入,让同一条工作流在受控参数下启动部署任务。
学习目标
- 使用
workflow_dispatch定义手动工作流及输入参数 - 在 Job 和 Step 中读取输入并根据参数控制执行
- 理解输入校验、默认值与生产部署保护的边界
定义可选择参数的工作流
workflow_dispatch 是 GitHub Actions 的手动触发事件。可以在 on.workflow_dispatch.inputs 下声明参数,并通过 required、default、type 等属性约束操作入口。
下面的工作流要求操作者选择部署环境和版本,并提供一个布尔开关决定是否执行数据库迁移:
name: Manual Deploy
on:
workflow_dispatch:
inputs:
environment:
description: Target environment
required: true
type: choice
options:
- staging
- production
version:
description: Version to deploy
required: true
type: string
run_migration:
description: Run database migration
required: true
default: false
type: boolean
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Show deployment plan
run: |
echo "Environment: ${{ inputs.environment }}"
echo "Version: ${{ inputs.version }}"
echo "Run migration: ${{ inputs.run_migration }}"
- name: Run migration
if: ${{ inputs.run_migration }}
run: echo "Running migration for ${{ inputs.version }}"
- name: Deploy
run: echo "Deploying ${{ inputs.version }} to ${{ inputs.environment }}"预期输出,例如选择 staging、输入版本 v2.4.0 并启用迁移后:
Environment: staging
Version: v2.4.0
Run migration: true
Running migration for v2.4.0
Deploying v2.4.0 to staging实际日志还会包含 GitHub Actions 为每个 Step 生成的运行信息;这里仅列出示例命令产生的关键输出。
参数怎样进入任务
手动启动时,GitHub 会先收集 workflow_dispatch 声明的输入,再创建一次 workflow run。任务运行后,可以使用 inputs.<name> 读取对应值,并将其放入表达式、环境变量或命令参数中。

choice 适合环境等有限集合,能减少拼写错误;boolean 适合明确的开关;string 适合版本号等开放值。即使界面要求必填,也不要把用户输入直接视为可信部署参数,例如版本号仍应在后续步骤中验证是否对应真实制品。
用参数控制任务边界
输入不仅可以传给命令,也可以参与 if 条件。示例中的迁移 Step 只有在 run_migration 为真时执行,因此无需维护两份几乎相同的部署工作流。
环境参数还可以与 GitHub Actions Environment 配合。生产 Job 可以通过表达式把 environment 输入绑定到 Job 的 environment 字段,再利用仓库中配置的 Environment 保护规则控制敏感部署。手动参数负责表达“要部署什么”,审批、权限和密钥管理则应由专门的安全机制负责。
手动验证一次工作流
工作流文件进入默认分支并满足 GitHub 的手动运行条件后,可以在仓库的 Actions 页面选择该工作流,通过 Run workflow 填写参数并启动。也可以使用 GitHub CLI 触发,便于验证参数是否正确传递:
gh workflow run "Manual Deploy" -f environment=staging -f version=v2.4.0 -f run_migration=true预期输出:
✓ Created workflow_dispatch event for manual-deploy.yml at <BRANCH>GitHub CLI 的具体成功提示可能随版本变化,<BRANCH> 代表实际目标分支;最终应在 Actions 中确认对应 workflow run 已创建,并检查任务读取到的环境、版本和布尔参数是否与提交值一致。
当部署动作需要人工决定目标环境、发布版本或可选步骤时,workflow_dispatch 比临时修改 YAML 或提交无意义 commit 更可控。真正的生产流程还应把参数校验、Environment 保护和最小权限配置一起纳入发布边界。