gh-aw Dispatch 模式教程：安全触发跨仓库执行的完整方法-平芜编程栈

gh-aw Dispatch 模式教程：安全触发跨仓库执行的完整方法

【免费下载链接】gh-awGitHub Agentic Workflows项目地址: https://gitcode.com/GitHub_Trending/gha/gh-aw

gh-aw是 GitHub Agentic Workflows 开源项目，让 AI 代理以声明式工作流的形式在 GitHub Actions 中安全运行。本教程完整讲解Dispatch 模式：如何通过workflow_dispatch手动触发工作流并传入自定义参数，以及如何用dispatch-repository安全地触发跨仓库执行——从安装、配置到三层安全机制，新手也能一次看懂。

一、什么是 Dispatch 模式？

Dispatch 模式是一种"按需手动触发"的工作流设计模式：工作流不依赖定时任务或代码事件，而是由人在需要时通过GitHub Actions 界面或gh aw CLI手动启动，并可传入自定义输入（如目标环境、研究主题、仓库名）。

典型使用场景：

🔍 研究类任务：按需让 AI 代理分析指定主题
🚀 CI 触发：手动启动构建、部署或验证流程
🧪 开发调试：测试阶段反复触发工作流验证逻辑
📦 跨仓库编排：在一个仓库中安全地唤醒另一个仓库的工作流

DispatchOps 模式的核心思想是"写操作全部交给安全输出"，官方文档可见 dispatch-ops.md。

二、快速安装 Dispatch 工作流

首先需要安装 gh-aw CLI。推荐方式是通过 git clone 获取项目后本地构建：

git clone https://gitcode.com/GitHub_Trending/gha/gh-aw

然后用gh aw add命令将工作流添加到目标仓库，或在 GitHub 仓库的 Actions 页面上手动创建 workflow 文件：

三、带自定义输入手动运行工作流

在on:中声明workflow_dispatch触发器，并定义输入参数，运行者每次触发时即可填入不同值：

on: workflow_dispatch: inputs: topic: description: '研究主题' required: true type: string depth: type: choice options: [brief, detailed] default: brief

支持string、number、boolean、choice四种输入类型，完整语法见 triggers.md。

从 GitHub 界面运行：进入 Actions 标签页 → 选择工作流 → 点击Run workflow→ 填写输入 → 确认。

从 CLI 运行（更适合自动化脚本）：

gh aw run research --raw-field topic="量子计算" --raw-field depth=detailed gh aw run research --wait # 等待运行完成 gh aw run research --ref my-branch # 指定分支运行

工作流内部通过${{ github.event.inputs.topic }}引用输入值，配合条件模板可以动态改变 AI 代理的行为。

四、跨仓库执行：dispatch-repository 触发器

这是 Dispatch 模式的进阶玩法。gh-aw 提供dispatch-repository安全输出类型，它会在外部仓库触发repository_dispatch事件，让本仓库的 AI 代理安全地唤醒另一个仓库的工作流。

⚠️ 注意：dispatch-repository目前是实验性功能，编译时会提示Using experimental feature: dispatch-repository。同仓库触发请使用dispatch-workflow（见下方对比）。

配置核心字段

每个dispatch-repository下的键定义一个暴露给 AI 代理的具名工具：

safe-outputs: dispatch-repository: trigger_ci: description: 在另一个仓库中触发 CI workflow: ci.yml # 转发到 client_payload.workflow 用于路由 event_type: ci_trigger # 发送的事件类型 repository: ${{ inputs.target_repo }} # 支持 Actions 表达式 inputs: environment: type: choice options: [staging, production] default: staging max: 1 # 单次运行最多触发次数

关键字段说明：

字段	必填	说明
`workflow`	✅	转发给接收方用于路由的工作流标识
`event_type`	✅	`repository_dispatch`事件的类型
`repository`/`allowed_repositories`	二选一	固定目标仓库，或允许 AI 代理从白名单中动态选择
`inputs`	可选	结构化输入 schema，随事件转发
`max`	可选	每次运行允许的最大触发次数（默认 1）

触发方式对比

对比项	`dispatch-workflow`	`dispatch-repository`
作用范围	仅限同仓库	跨仓库
机制	运行时`workflow_dispatch`API	`repository_dispatch`事件
验证	编译期校验工作流存在	运行时白名单校验目标仓库

五、三层安全机制：跨仓库执行为什么可靠

gh-aw 对 Dispatch 执行做了系统性防护，这也是它区别于"裸调 API"的关键：

编译期验证— 同仓库触发时，编译器会校验目标工作流文件是否存在（.md/.yml/.lock.yml）、是否声明了对应触发器、是否自我引用，配置错误在编译阶段就被拦截。
运行时白名单（SEC-005）—dispatch-repository触发前，处理器会校验目标仓库是否匹配配置的repository或allowed_repositories，不在白名单内的目标直接拒绝。
Staged 预览模式— 支持staged: true，先预览将要触发的内容而不实际发出，适合首次配置时的安全演练。

此外，dispatch-workflow还内置了速率限制：连续触发之间自动间隔 5 秒，保护 GitHub API 配额。跨仓库读取数据时，还可以用tools.github.allowed-repos把代理的读取范围限定在特定仓库，防止越权访问，详见 cross-repository.md。

六、实战示例：从中心仓库触发其他仓库的 CI

想象一个多仓库组织：中心仓库负责编排，组件仓库各自有独立 CI。在中心仓库的 Dispatch 工作流中声明：

safe-outputs: dispatch-repository: notify_service: workflow: ci.yml event_type: ci_trigger allowed_repositories: - org/service-a - org/service-b inputs: message: type: string

运行时 AI 代理会从白名单中选择目标仓库，携带workflow、event_type和结构化inputs发出事件；接收方仓库中监听该event_type的工作流随即被唤醒。若只需固定触发单一仓库，把allowed_repositories换成repository: org/service-a更简单。