我最早把 GitHub Actions 当定时任务用的时候总觉得哪里不对劲有些流水线一周跑一次可以有些是临时想跑、有明确触发条件或参数要传但 push、schedule 这些“自动事件”根本照顾不到。后来真正开始用 workflow_dispatch 这门“手动触发”技能才发现自己不是缺一两个按钮而是缺一套按需运行工作流的完整思路。这篇东西不是给你念文档是我把 Web 界面、API、命令行三种手动触发方式的配置、调用和踩坑完整捋了一遍适合所有用 GitHub 跑 CI/CD 流程的开发者参考。1. 手动触发不是“多个按钮”那么简单1.1 为什么自动化工作流还需要手动触发只要是真心把 CI/CD 用起来的人迟早会撞上“必须让一个人点一下”的场景。定时任务和 push 事件看似自动化但覆盖不了日常开发里那些“不确定什么时候发生、但发生时需要立刻处理”的操作。我举几个最常见的例子半夜线上出问题你需要立刻回滚某次发布产品经理临时说“这版镜像先别发生产先发到 staging 验证一下”你写了一个数据修复脚本想对着某一天的数据跑一次今天跑完明天可能还要跑。这些操作有一个共同点执行时机不可预测且每次执行往往需要不同的参数。如果全靠代码改动触发或者靠定时任务傻等不仅浪费流水线资源还会让真正该被自动化省掉的人力反而变得更重。手动触发的意义不是“回到手动时代”而是给自动化业务流程留一个人工决策入口。尤其是多环境部署、手动验收、紧急回滚这类场景人工确认和按需执行本来就是流程的一部分。GitHub Actions 提供的 workflow_dispatch 事件本质上就是给工作流加一个“启动开关”让你能在任意时间、针对任意分支、带上自定义参数把流程重新拉起来。1.2 三种触发方式的选型逻辑我平时在实际项目中会同时用到三种手动触发方式它们各自的价值不太一样触发方式使用场景适合谁Web 界面点击临时手动跑一次、查看参数选项所有开发者、刚接触 GitHub Actions 的新手REST API 调用将触发逻辑集成进自有平台、跨系统调度平台工程师、有自动化运维需求的人GitHub CLIgh开发者在终端里快速触发、本地脚本串联习惯命令行工作流的开发者选型逻辑其实很简单人在电脑前、偶尔点一次首选 Web 界面要写脚本或让外部系统来触发API 是唯一正路终端党并且希望触发后马上盯日志gh 命令要比 Web 页面体验好。三种方式背后用的是同一个 workflow_dispatch 事件只是“打开开关”的入口不同所以你不需要把配置分三套学核心就一个。2. 核心配置workflow_dispatch 这样写才不踩坑2.1 最小配置先把手动触发跑起来一个工作流要被手动触发唯独需要在 YAML 文件的 on 字段里声明 workflow_dispatch。先给你看一份最简单的配置文件name: Manual Deploy on: workflow_dispatch: jobs: ping: runs-on: ubuntu-latest steps: - name: Run a one-line script run: echo 手动触发成功了这段配置提交到默认分支通常是 main 或 master之后打开仓库的 Actions 标签页选中左侧这个工作流右上角就会出现一个【Run workflow】按钮点进去选好分支按绿色按钮运行即可。这里有一个很多人第一次接触时容易忽略的点workflow_dispatch 配置必须存在于目标分支里。如果你的工作流文件只在 main 分支上那 Web 界面的分支下拉框里只有提交过该文件的那些分支才能当作运行目标。很多新手踩过这种坑在 feature 分支新增了 workflow_dispatch结果去 Actions 页面切换分支时找不到或者看到按钮但点击后跑的是 main 分支。别指望从哪个分支都能看到这是一个容易混淆的细节。2.2 inputs 参数手动触发真正的威力所在绝大多数手动触发的工作流多多少少都需要运行时输入参数。GitHub Actions 提供的 inputs 字段就是为这个场景准备的。通过 inputs你可以让工作流从外部接收字符串、多选项、布尔值甚至环境名不同参数组合决定流水线后续的行为。我常用的一个发布配置大致长这样name: Deploy on: workflow_dispatch: inputs: environment: description: 选择要发布的环境 required: true default: staging type: choice options: - staging - production version: description: 镜像版本号例如 v1.2.3 required: true default: latest type: string is_hotfix: description: 是否为热修复发布 required: false default: false type: boolean jobs: deploy: runs-on: ubuntu-latest steps: - name: Print inputs run: | echo 环境: ${{ github.event.inputs.environment }} echo 版本: ${{ github.event.inputs.version }} echo 热修复: ${{ github.event.inputs.is_hotfix }}inputs 支持的类型我在项目里基本都用过它们的表现差别不小string最通用的文本输入框适合填版本号、镜像标签、日期等自由文本。choice下拉选项适合有限集合比如 staging、production、testing 这种环境列表。boolean勾选框适合 is_rollback、skip_tests 这类开关型参数。environment下拉选择环境和 choice 类似但会有真实的环境对象关联适合启用了 Repository environments 保护规则的项目。这里说一个细节GitHub Actions 早期版本只支持 string 类型type: choice 和 type: boolean 是在 2021 年左右增加的。如果你的 workflow 文件是在老仓库里直接用模板改造注意不要写出哨兵语法导致 YAML 解析失败。另外在后续步骤中读取参数时可以通过${{ github.event.inputs.参数名 }}读取也可以配合env:字段预先赋值这样后续步骤引用起来更清晰。2.3 限制并发与保护规则别让手动任务叠成山手动触发只解决了“可随时运行”的入口问题但没有解决“别同时跑一堆互相打架的任务”的问题。比如部署任务如果同时触发两次后一次的部署操作很可能覆盖前一次轻则产生脏数据重则发布错版本。我的习惯是给所有手动部署类工作流加上并发限制。GitHub Actions 的 concurrency 关键字可以做到这一点concurrency: group: deploy-${{ github.event.inputs.environment }} cancel-in-progress: true这段配置用 environment 作为并发分组的 key意味着同一个环境的手动任务只允许一个在跑新任务过来时旧任务会被取消。对于发布类任务我曾经也犹豫过要不要把 cancel-in-progress 设成 false让新任务排队而不是取消老任务但实际用下来部署任务几乎是“后来者覆盖前者”的逻辑取消旧的跑新的更合理。如果场景是数据迁移、批量任务这种前后有依赖关系的操作就务必把 cancel-in-progress 设为 false避免误杀正在执行的任务。如果你的项目启用了 Environment Protection Rules还可以把 environment 类型输入和真实环境对象绑定这样只有通过审批或满足保护条件才能继续发布。这个组合用法对于生产环境发布流程尤其重要相当于在手动触发之外再加了一道人工审核闸门。3. 手动触发的三种实操方式从界面到命令行3.1 Web 界面触发5 分钟上手的最短路径Web 界面触发非常适合临时执行和快速验证。在仓库主页面点击 Actions 标签左侧能看到所有声明了可触发事件的工作流。找到你要运行的那一个工作流名称旁边默认会展示最近一次运行的记录页面右上角是【Run workflow】按钮。点击按钮后会弹出一个面板里面包含分支选择下拉框以及你在 inputs 中定义的所有字段。选择分支后填好参数点击绿色的【Run workflow】任务就会出现在运行列表里。随后你可以点击这条运行记录实时查看 job 和 step 日志。这一步的逻辑跟 push 触发的运行完全一样错误信息、重试步骤都能正常使用。我刚开始用 Web 界面触发时犯过一个非常低级的错误填完参数直接点了按钮结果忘记确认分支下拉框里的目标分支。因为默认分支往往不是我要部署的 feature 分支于是白白跑了一个构建出包最后是从日志里才发现目标分支不对。现在我已经形成肌肉记忆点击前一定检查三个东西——工作流名称、目标分支、输入参数。这三个确认完再去点绿色按钮基本万无一失。3.2 通过 REST API 触发把手动操作变成自动化接口Web 界面适合人用但如果你要在自己的运维平台里做一个“一键发布”按钮或者想在某个系统事件触发后调用 GitHub Actions 去跑流程那就得用 API。GitHub Actions 的手动触发 API 有两条关键路径。第一步先拿到工作流的 ID。可以这样调用curl -H Accept: application/vnd.githubjson \ -H Authorization: Bearer YOUR_GITHUB_TOKEN \ https://api.github.com/repos/OWNER/REPO/actions/workflows返回的 JSON 数组中会有每个工作流的 id、name、path 等信息找 name 匹配的那个即可。拿到 workflow_id 后第二步才是触发curl -X POST \ -H Accept: application/vnd.githubjson \ -H Authorization: Bearer YOUR_GITHUB_TOKEN \ https://api.github.com/repos/OWNER/REPO/actions/workflows/WORKFLOW_ID/dispatches \ -d {ref:main,inputs:{environment:staging,version:v1.2.3,is_hotfix:false}}注意几个关键点。第一token 需要有 workflow 权限或者仓库的写权限默认的 GITHUB_TOKEN 在受信任的工作流里可以直接用但如果你是外部系统调用推荐创建 Fine-grained personal access token仓库权限里勾上 Actions 的 Read and write。第二POST 请求的 ref 参数必须是分支名或标签名不能填 commit SHA。第三一旦请求成功API 不会返回 201 带 payload而是返回 204 No Content很多新手看到“没有响应体”会以为调用失败其实恰恰是成功了。之后过几秒去仓库的 Actions 页面就能看到新任务。还有一个可以偷懒的路径不需要先查 workflow_id。如果工作流文件路径在仓库里是固定且已知的比如 .github/workflows/deploy.yml你可直接在工作流页面的 URL 中看到路径信息甚至在某些 API 场景下你可以先通过 GET 请求拿到 ID 再触发这已经是官方推荐的标准流程了。3.3 使用 GitHub CLIgh触发终端党的效率神器GitHub CLI 是近两年我个人使用频率最高的触发方式。它把 Web 界面里“选工作流、填参数、跑”的流程压缩成了两条终端命令还省去了在浏览器和终端之间来回切换的麻烦。先看工作流列表gh workflow list输出会列出所有可用工作流找到你要触发的那个名称。然后直接运行gh workflow run Deploy --ref main \ -f environmentstaging \ -f versionv1.2.3 \ -F is_hotfixfalse-f 表示 string 类型参数-F 表示自动识别类型。这里有一个细节我很早就踩过如果你用 -f is_hotfixfalse这个参数会以字符串方式传进去而工作流里对应类型是 boolean那在条件判断时可能会得到意想不到的结果。后来我一直用 -F 传布尔值或数字让 gh 自行转换类型。想盯着执行情况可以用gh run watch它会进入实时日志模式类似 tail -f。如果你的流水线要跑几分钟这个命令非常有用不用反复刷新网页。还有一条命令gh run list可以快速查看最近的工作流运行记录结合gh run view RUN_ID --log能拉取历史日志排查问题比网页控件还快。3.4 从外部系统发起手动触发的正确姿势如果你想在自有平台里加一个“触发 GitHub Actions 的按钮”API 调用只解决了一半问题另外一半是认证和权限管控。推荐使用 GitHub App 安装认证而不是把某个人的 Personal Access Token 硬编码在服务端。GitHub App 可以通过私钥生成短期 installation token既安全又能细粒度控制权限token 可以每 10 分钟刷新一次比直接放着长期 token 安心得多。用 GitHub App 触发工作流时安装权限里需要勾选该仓库的 Actions 读写权限然后通过 App ID 私钥生成 JWT再换取 installation access token。这个链路听起来复杂但官方文档里有 Python、Node.js 等语言的示例代码照着接一遍就能跑通。如果只是个人项目或内部工具用 Fine-grained PAT 明显更轻量注意把 token 存到组织的 secret 里不要明文写在脚本里。4. 典型场景拆解手动触发应该用在哪些地方4.1 多环境按需发布多环境发布几乎是手动触发最标准的场景。比如你有一套 CI 流程测试通过后需要人工决定是否发布到 staging 或 production。如果选 push 触发那每次推送都会带动一次构建和部署容易造成资源浪费如果选定时触发发布时机跟真正需求对不上。用 workflow_dispatch choice 参数后整个发布动作被压缩成一次人工决策选择目标环境点击运行。流程内部再根据参数走不同的脚本或 jobjobs: deploy: runs-on: ubuntu-latest if: github.event.inputs.environment production environment: production steps: - run: ./deploy.sh production如果生产环境配置了 branch 保护或 environment 审批那就算手动触发成功也要等审批通过才会实际执行。这一点非常有用等于给“按需发布”又加了一道人工确认关卡。4.2 版本回滚与热修复线上出问题时最怕的就是“找到该回滚的版本却发现流水线不能直接跑”。如果能手动触发一个回滚工作流并且输入参数里带上目标版本号这个过程会变得非常顺畅。我通常会在部署工作流基础上增加一个rollback输入参数或者单独写一个 rollback 工作流。回滚工作流接收 version 参数直接把目标镜像或代码版本部署回线上。关键是 version 参数一定要用 string 输入框不要写成写死的下拉选项因为历史版本号是持续增长的不可能在下拉框里列全。当然回滚任务一般建议加人工确认步骤在环境审批里卡一道防止误操作。4.3 定时任务的“补跑”入口很多团队会用 schedule 事件实现每天定时跑数据清洗或报表生成但定时任务偶尔会挂掉一旦挂掉就要等第二天才重跑。这种场景下同一个工作流加上 workflow_dispatch 后就具备了“补跑”能力。我常用的做法是在工作流里增加一个 date 输入参数默认取当前日期on: schedule: - cron: 0 3 * * * workflow_dispatch: inputs: report_date: description: 业务日期 required: true default: type: stringjob 里再做一个判断如果 report_date 为空则用当前日期否则用传入的日期。这样定时任务每天正常跑任何时候失败了都可以手动指定日期快速补跑同一套流程。这个小模式救过我很多次每次数据管道报错时不用改代码、不用写临时脚本直接点一下按钮就行。4.4 团队协作中的人工闸门当多个开发者在同一个仓库上维护工作流时手动触发还承担着“人工闸门”的功能。比如某些构建任务会读取外部 Secret或者会向正式环境写入数据这些操作不应该被随便一个 push 事件触发但又要保证具备相应权限的成员可以随时运行。workflow_dispatch 可以和 required reviews 配合使用。你可以在分支保护规则中设置“在合并之前需要拉取请求审查”但 Actions 的触发入口并不直接受此限制真正起闸门作用的是上文中提到的 environment 审批规则或者你在 job 里加一层人工确认步骤用 environment 的 reviewers 配置卡住生产环境任务。手动触发 审批比任何“禁止 push 到 main”的规则都更贴合实际发布流程。5. 常见问题与排查技巧实录5.1 为什么没有 Run workflow 按钮这是新手最常见的问题没有之一。工作流声明了 workflow_dispatch但 Actions 页面上就是找不到【Run workflow】按钮。排查顺序我总结成了固定套路确认 workflow_dispatch 是否确实写在 on 字段里的工作流配置中别写在某个 job 里了。确认当前查看的分支是否包含该工作流配置。只有工作流文件存在且已经提交到该分支按钮才会出现。确认你是不是仓库管理员或有写权限。只读用户看不到 Run workflow 按钮这其实是一个安全设计不是 bug。确认浏览器缓存。有时候 GitHub 的 Web 界面缓存比较顽固切换分支或刷新后按钮还不出现强制刷新或换个隐私窗口看看。这个排查顺序基本能解决 99% 的“按钮失踪”问题。剩下 1% 的情况是工作流本身 YAML 语法错误导致 Actions 没有正确解析触发事件。这种情况通常会同时出现配置错误的提示去 Actions 页面确认一下有没有语法报错即可。5.2 API 触发返回 404 或 422 时的典型原因如果你用 API 触发失败先看返回码不同状态码指向的问题完全不同。404 通常意味着仓库不存在、token 无权访问、或者 workflow_id 写错。特别是 Fine-grained token如果只给了 metadata 读取权限而没有 Actions 读写权限接口会直接返回 404这其实是 GitHub 为了防止探索私有仓库信息刻意伪装成 404。422 则通常是 ref 参数不存在或者 inputs 里有必填参数没传。比如工作流里声明了 version 必填但 POST 请求的 inputs 里没有 versionAPI 会返回 422 Unprocessable Entity。解决方式也很直接先在浏览器里手动触发一次确认参数名和类型完全一致再按同样参数去调 API。很多时候失败是因为大小写、下划线写法和 YAML 里不一致比如 YAML 定义的是versionAPI body 写成Version那就会提示错误。我用这个方法排查过好多次基本都能一两分钟内定位。5.3 fork 仓库和 PR 场景下无法手动触发在 fork 出来的仓库里Actions 默认是不允许直接被第三方提交的代码执行敏感命令的。如果你 fork 了一个项目想在自己的 fork 上手动触发工作流其实并不是完全不行——前提是你对 fork 后的仓库本身有写权限且工作流文件里确实有 workflow_dispatch。这个场景下手动触发是可行的因为你是仓库所有者。但是来自 fork 的 Pull Request 不会自动执行工作流这是 GitHub 的安全策略防止恶意代码在父仓库的 Runner 上运行。如果你的工作流必须支持 fork PR 场景正确做法是在 push 或 pull_request_target 事件中处理Workflow dispatch 不适合这种协作模式。而“PR 来自 fork 但想手动触发 CI”这个诉求它本身也是一个安全风险极高、文档也很少提到的领域我的建议是避免把这套逻辑塞到手动触发里老老实实用原生 pull_request 事件。5.4 手动触发频率限制与权限控制GitHub Actions 对 workflow_dispatch 是有调用频率限制的。API 方面Go to repository 的 Actions 相关接口一般遵循标准 REST API 的 secondary rate limitWeb 界面本身没有严格次数控制但 API 调用如果过于频繁会收到 429 Too Many Requests 或 rate limit 报错。如果你的自动化脚本要批量触发多个工作流注意在两批请求之间加一点延迟不要无脑循环。权限控制方面Web 界面触发需要写权限API 触发需要 Actions read/write 权限。这里有一个设计小心得如果某个工作流只允许指定的人手动运行最可靠的方式是给相关 Environment 增加保护规则在 job 层面把该环境与输入参数绑定。我见过太多团队把发布权限直接开放给所有有仓库写权限的人这会让手动触发变成一个隐患。通过 environment配合 required reviewers 机制可以相对优雅地把“谁可以手动触发生产部署”这个问题变成受控的审批流程。最后再分享一个我自己的使用习惯这套手动触发玩法用久了我最大的体会是GitHub Actions 里没有“只能这样”的绝对规则关键是先明确你希望谁来触发、什么时候触发、带什么参数触发。最常见的组合拳是把 Web 界面留给临时操作把 API 集成到内部工具平台把 gh 命令沉淀成自己日常开发环境里的快捷命令。还有一个非常提升幸福感的小技巧把常用参数的默认值设好。比如 staging 环境的参数默认值永远是最安全的那个这样团队成员只需要点一个按钮不用每次费力思考参数。我甚至会把“默认值即安全值”写进团队约定里这样手动触发带来的自由度不会变成一团混乱。如果你还只是在 Actions 里点过几次 Run workflow建议现在就去试一试写带 inputs 的工作流再试试用 gh 命令跑一次上手成本很低但能帮你省下很多重复操作的时间。
