工作流 📋 6 个步骤 第 631 / 632 篇

用 GitHub Agentic Workflows 把编码 Agent 放进 Actions:gh aw 编译、safe-outputs 申请单与每日额度闸门

GitHub Agentic Workflows 让开发者只用一份 Markdown 定义「触发条件 + 权限 + 安全输出 + 预算」,再编译成带固定版本的 Actions 工作流。本教程按官方文档六步落地:装 gh aw 扩展、init 备好仓库、写第一份 frontmatter、compile --strict 并读 lock 头部元数据、用 safe-outputs 把写权限收成申请单、三层额度与频率闸门、最后干跑首跑并用 logs 复盘。

2026.11.18· 14 分钟上手· 约 4405 字· ⚙️ gh-aw / 🧱 safe-outputs

把编码 Agent 放进 CI 里跑,最难处理的从来不是「它会不会写代码」,而是它会不会在你没看见的时候直接改仓库、花掉一整天的额度。GitHub Agentic Workflows(命令行叫 gh aw)给出的答案是:你只写一个 Markdown 文件,前面用 YAML 声明触发条件、可用工具、能申请哪些写操作、每天最多花多少 AI 额度,GitHub 把它编译成一份带固定版本的 Actions 工作流,Agent 在沙箱里读、把想做的写操作作为「申请」提交,再由另一个拥有窄权限的作业真正执行。

🧩 适合谁:想让「每天自动分诊 issue」「PR 挂了自动查原因」「文档跟着代码更新」这类事不再靠人盯的团队。前置准备:一个 GitHub 仓库(建议先拿测试仓库)、已安装并登录的 GitHub CLI(gh)、仓库允许运行 Actions、以及一个可用的引擎账号(默认 Copilot,也可换 Claude、Codex、Pi)。整个过程不需要你在本地跑模型。

四条先记住的边界:① 工作流跑在 GitHub Actions 里,会同时消耗 Actions 分钟和 AI 额度,一次配置失误可能连跑几十次;② safe-outputs 不是人工审批,而是「按类型和条数限额的申请通道」,你声明了 create-pull-request,Agent 就有权申请开 PR;③ 只改 Markdown 正文不必重编译,改 frontmatter 必须重编译,否则运行的还是旧配置;④ 从别人仓库 gh aw add 工作流前,先读完它的触发条件、权限、工具与安全输出,它会在你的仓库里以你的额度运行。

动手之前把清单过一遍,缺哪一项都会卡在中途,而且报错信息通常不会直接告诉你缺什么。

前置项怎么确认缺失后的典型表现
GitHub CLI 已登录gh auth status 显示已登录且有 repo scopegh aw 子命令报认证或 403
仓库允许 Actions仓库 Settings 里 Actions 未被禁用工作流能编译但永远不触发
引擎凭据可用按引擎文档配好令牌,或确认组织已开通对应额度运行启动后立即在激活阶段失败
默认分支可推送有写权限,或准备走 --create-pull-request--push 被分支保护拒绝
测试仓库不要拿生产仓库做第一次尝试试错成本直接从「一条评论」变成「一堆 PR」

先弄清:Markdown 是源文件,lock.yml 才是真正跑的东西

gh-aw 的心智模型只有一句话:你写的是「给 Agent 的任务书 + 一张权限清单」,编译产物才是 Actions 认识的 YAML。两者必须一起提交,因为 Actions 只读 lock 文件。

概念位置作用改动后要不要重编译
工作流源文件.github/workflows/<name>.mdYAML frontmatter 定权限,正文是 Agent 指令改正文不用;改 frontmatter 要
编译产物.github/workflows/<name>.lock.yml带固定提交 SHA 的 Actions 工作流,标注「自动生成,请勿编辑」由 gh aw compile 生成
元数据头lock 文件第一行gh-aw-metadata 记录 schema 版本、frontmatter 哈希、strict 与引擎随编译刷新
依赖清单lock 文件头部注释列出用到的 secrets 与被固定的外部 action 版本随编译刷新
💡 这个设计的好处是「可审计」:你不用读几千行 YAML,只看 lock 文件头就知道这次运行会用到哪些密钥、钉住了哪些 action 版本。评审 PR 时先看这两块,比逐行读生成的 YAML 有效得多。

「Agent 只读、写操作另起作业」不是一句口号,它由六层叠起来。理解分层的好处是:出问题能判断该改配置,还是该换运行环境。

层拦什么你能调的地方
编译期校验schema 错误、非法表达式、未固定的 actiongh aw compile --strict
隔离沙箱Agent 直接接触宿主凭据与文件系统运行环境选择(Docker、自托管 runner)
完整性过滤不可信来源的内容进入推理按作者信任度与合并状态设置策略
网络出口Agent 任意外联导致的泄密network.allowed 白名单
威胁检测可疑输出(提示注入痕迹、越权意图)拦截或转人工复核的策略
安全输出未声明的写操作safe-outputs 的类型、条数、对象约束

「默认安全」有前提:这六层保护的是「按默认模型跑、只用内置工具」的场景。一旦你在 steps 里塞自定义脚本、或用 jobs 挂自定义安全输出,就等于自己在那条链上开了口子——这部分需要单独评审,不能指望默认策略兜住。

Step 1:装扩展、初始化仓库、看清它写了哪些文件

1 一条命令装好,一条命令把仓库备好

官方有两条安装路线:作为 gh 扩展安装,或跑安装脚本。装完先验证版本,再初始化——init 会往仓库里写五类文件,值得逐一确认再提交。

# 路线 A:作为 gh 扩展安装(可固定 tag 或 SHA)
gh extension install github/gh-aw
gh aw version

# 路线 B:官方安装脚本(装到 ~/.local/share/gh/extensions/gh-aw/)
curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash

# 初始化当前仓库
gh aw init

# 看清楚它动了什么,再提交
git status

gh aw init 的产物包括:把 .lock.yml 标记为生成文件的 .gitattributes、给编码 Agent 用的调度技能 .github/skills/agentic-workflows/SKILL.md、.vscode/settings.json、gh-aw 的 MCP 配置 .github/mcp.json,以及 .github/workflows/copilot-setup-steps.yml。如果你的引擎不是 Copilot,加 --engine claude 可跳过 Copilot 专属产物。

先别急着 push:init 会在仓库里新增 MCP 配置与技能文件,这些东西会改变编码 Agent 在你仓库里的行为。团队仓库建议走 gh aw init --create-pull-request,让别人有机会看一眼再合并。

命令不多,但每个的边界要清楚。下面这张表按「从零到能跑」的顺序排,遇到不确定时先查它,别去猜参数。

命令作用本教程用到的地方
gh aw init初始化仓库:gitattributes、调度技能、MCP 配置、setup 工作流Step 1
gh aw new按模板生成一份新的 .md,可用 --engine 注入引擎没有现成模板时
gh aw add从其他仓库引入工作流,支持 @v1.0.0 固定版本复用社区工作流
gh aw compile把 .md 编译成 .lock.yml,可加 --strict、--dry-runStep 3
gh aw run手动触发,--dry-run 只预览,--push 顺带提交Step 6
gh aw status / logs看启用状态与历史运行,logs 可只要用量或轨迹Step 6
gh aw fix / upgrade跑 codemod 修语法;upgrade 还会重编译全部工作流版本升级后

Step 2:写第一份工作流,frontmatter 只留最小集

2 一个「新 issue 自动回一条有用信息」的完整例子

下面这份文件放在 .github/workflows/issue-triage.md。上半部分是配置,下半部分是自然语言指令;指令里可以直接引用 Actions 上下文,例如 issue 编号。

---
on:
  issues:
    types: [opened]

permissions:
  contents: read
  issues: read

engine: copilot

tools:
  github:
    toolsets: [issues]
  bash: ["gh issue view"]

network: defaults

safe-outputs:
  add-comment:
    max: 1

max-turns: 10
---

# Issue 初诊

读取 issue #${{ github.event.issue.number }}。

1. 用一句话复述用户到底想解决什么问题。
2. 判断它更像 bug、功能请求还是使用问题,并说明依据。
3. 列出你需要用户补充的两条信息。

只输出一段 Markdown 评论,不要复述原文,不要承诺修复时间。
字段这份配置里的取值为什么这么写
onissues: types: [opened]只在新建 issue 时跑,避免评论触发自己形成循环
permissions只给 contents: read 与 issues: readAgent 阶段不需要写权限,写走 safe-outputs
enginecopilot(省略也是默认)可换 claude、codex、pi;gemini 已弃用,agy 为实验性
tools只开 issues 工具集与一条 bash工具越少,选错工具的概率越低,攻击面也越小
safe-outputsadd-comment: max: 1一次运行最多发一条评论,防刷屏
max-turns10默认 500,对简单任务太宽松
💡 没有写 safe-outputs 时,编译器会自动注入一条 create-issue(上限 1 条)。这意味着「我什么都没声明」并不等于「Agent 什么都不能写」,所以要把真正需要的输出类型写清楚。

触发条件与权限是最容易写成「能跑但跑错」的两处。先把常见的三组搭配记住,再按业务改:

想做的事on 写法permissions 最小集
新 issue 自动初诊issues: types: [opened]contents: read、issues: read
PR 失败后查原因workflow_run: workflows: ["CI"], types: [completed]contents: read、actions: read、pull-requests: read
每天整理一次文档schedule: cron: "0 1 * * *"contents: read(写走安全输出)

权限只读不代表安全输出能写:两者是两套机制。Agent 阶段的 permissions 决定它能读什么;真正落库的写操作由独立作业带着自己的窄权限执行,来源是你在 safe-outputs 里声明的类型。把 permissions 写成 write 不会让安全输出更宽松,只会让 Agent 本身多出写能力。

等这条单智能体工作流跑顺了,再考虑拆角色:官方文档说明,工作流文件可以在正文之后追加内联子智能体(inline sub-agents)定义,把「查原因」和「写结论」拆成两个角色。本教程不展开它的语法,因为那属于另一页参考,凭印象写层级很容易编译失败——先用单体版本把触发、权限、输出跑通,收益更直接。

Step 3:编译,然后读 lock 文件的头部三件事

3 编译是校验,也是审计入口

编译不只是格式转换,它会在生成前做 schema 校验、表达式白名单检查和 action 固定版本处理。加 --strict 让不合规的写法直接失败,而不是降级放行。

# 编译单条工作流,严格模式
gh aw compile .github/workflows/issue-triage.md --strict

# 只校验、看差异、不落盘(适合 CI 里跑)
gh aw compile --dry-run --strict

# 看生成的产物
Get-Content .github/workflows/issue-triage.lock.yml -TotalCount 25

打开 lock 文件,先看三处:第一行的 # gh-aw-metadata: {...}(含 schema 版本、frontmatter 哈希、strict 与引擎标识);Secrets used 列表(这次运行会碰哪些密钥);Custom actions used 列表(每个外部 action 都钉在具体 SHA 上,后面用注释标版本)。三处都对,才把 .md 与 .lock.yml 一起提交。

最常犯的错:改了 frontmatter 里的 safe-outputs 或 permissions,但忘了重编译,于是线上跑的还是旧权限。判断规则很简单——两个 --- 之间的改动都要重编译;正文改动直接生效。另外 lock 文件第一行是机器可读元数据,不要手工编辑。

Step 4:用 safe-outputs 把「写权限」收窄成一张申请单

4 Agent 只提议,落库由另一个作业执行

默认安全模型是「读、提议、检查、应用」:Agent 在隔离沙箱里读仓库,把要做的写操作作为结构化输出提交;另一个独立作业带着窄权限执行,中间还有内容清洗与威胁检测。你声明的每个输出类型都有自己的上限。

输出类型默认上限适用场景
create-issue1把发现的问题立成待办;未声明任何输出时会自动注入
add-comment1在 issue / PR / discussion 下回一条结论
create-pull-request1带代码变更提 PR,让人评审后合并
add-labels / remove-labels5 / 3打标签分诊,可用 allowed 限定可写标签
update-issue1改写标题/正文,operation 可选 append、replace 等
dispatch-workflow3触发另一条工作流,串成流水线
safe-outputs:
  add-comment:
    max: 2
    required-labels: [needs-triage]
    hide-older-comments: true
  add-labels:
    allowed: [bug, question, area/*]
    max: 3
  create-pull-request:
    max: 1
💡 allowed 与 required-labels 这类约束比「把上限调小」更有用:它们限制的是「能对什么对象做什么」,而不是「能做几次」。给 Agent 的写操作加上对象级前置条件,比事后看日志省力得多。

Step 5:预算与频率闸门,别让一次配置失误烧掉一天额度

5 三层刹车:单次、每日、按人

gh-aw 的额度单位是 AI Credits(AIC)。三层的分工是:max-ai-credits 管一次运行,max-daily-ai-credits 管同一条工作流 24 小时累计,user-rate-limit 管「同一个人能触发几次」。

max-ai-credits: 500            # 单次运行的额度上限(默认 1000)
max-daily-ai-credits: 2000     # 24 小时累计上限,超了直接跳过 Agent
max-turns: 12                  # 单次对话轮次上限(默认 500)

user-rate-limit:
  max-runs-per-window: 3       # 每个用户每窗口最多 3 次(1-10)
  window: 60                   # 窗口长度,分钟(默认 60,最大 180)
  events: [issues, issue_comment]
  ignored-roles: [admin, maintain]

默认值有两处口径不一,务必自己显式写死:首页写「max-daily-ai-credits 默认 5,000 AIC」,而 frontmatter 参考页写该字段「默认禁用」。两处说法冲突时,以你在 gh aw compile 后的实际校验结果为准——把值显式写进 frontmatter,就不会受默认值口径影响。同理,max-turns 默认 500,对绝大多数任务都过于宽松。

还有一处容易忽略的成本来源:--repeat 3 表示在首次之外再跑 3 次,也就是总共 4 次。调提示词时用 gh aw run <name> --dry-run 先看会触发什么,别直接 --repeat 试探。

额度怎么估才不至于拍脑袋?按「轮次 × 单轮成本」粗算:每轮要把工具结果再读一遍,轮次越多,重复上下文越多。所以压成本的顺序是先压轮次,再压工具返回体积,最后才考虑换便宜模型。

现象说明问题在哪优先动作
轮次远高于预期任务描述含糊,Agent 在反复试探正文里写清步骤与「不要做什么」,并调低 max-turns
轮次正常但单轮很贵工具返回太大(整文件、整页日志)收窄工具集,或让 Agent 先摘要再读细节
同一条工作流每天烧很多触发条件太宽(例如每次评论都跑)加 user-rate-limit,或改成标签/指派触发
偶发一次特别贵失败重试或长日志导致上下文爆炸用 max-ai-credits 兜住单次上限

Step 6:干跑、首跑、复盘,形成闭环

6 从「会不会跑」到「跑了什么、花了多少」

第一次运行建议手动触发,而不是等 issue 事件。把推送与触发拆开看,出问题时容易定位。

# 1) 先干跑:只预览会触发什么,不真的执行
gh aw run issue-triage --dry-run

# 2) 提交并推送,然后手动分发一次
gh aw run issue-triage --push

# 3) 看状态(enabled/disabled、上次结果)
gh aw status

# 4) 复盘这次运行:只要用量与 Agent 轨迹
gh aw logs issue-triage --artifacts usage,agent

# 5) 升级 CLI 或语法踩坑后批量修复
gh aw fix --write

gh aw logs 的 --timeout 是整数分钟(写 --timeout 5),这一点与 audit 用的 Go duration 写法不同,别混。若某次运行失败,把失败链接交给编码 Agent 并附上官方调试提示 https://raw.githubusercontent.com/github/gh-aw/main/debug.md,让它按日志定位,比人肉翻 Actions 页面快。

💡 想把「改提示词」与「改配置」分开验证:先只改正文(不用重编译)跑一次,确认输出格式对了;再动 frontmatter 里的工具与输出类型。两个变量一起改,出问题就说不清是哪边引起的。

做到哪一步算成功

检查项期望现象对应步骤
扩展可用gh aw version 有输出,gh aw init 生成五类文件Step 1
源文件合规gh aw compile --strict 通过,无警告降级Step 2、3
产物可审计lock 文件首行有 metadata,头部列出 secrets 与固定 action 版本Step 3
写权限受控Agent 只产出申请,评论/PR 数量不超过 maxStep 4
预算生效额度用尽时该次运行跳过 Agent,而不是继续烧Step 5
可复盘gh aw logs --artifacts usage,agent 能看到轮次与用量Step 6
🎉 到这里你已经把「一个会自己动手的 Agent」变成了「一个只能在声明范围内提案、且有预算上限的同事」。接下来要扩能力,优先加 safe-outputs 的类型与对象约束,而不是直接给 Agent 开写权限。

常见问题速查

现象大概率原因与处理
改了配置但线上行为没变改的是 frontmatter 却没重编译;跑 gh aw compile <file> 后再提交 lock 文件
编译报 schema 错误字段名或层级写错;对照 frontmatter 参考逐个核,别凭记忆写 safe_outputs 这种下划线形式
Agent 一上线就开了个 issue没有声明 safe-outputs 时自动注入 create-issue;显式写 create-issue: false 或声明真正需要的类型
运行被跳过,没有日志先看是否触到 max-daily-ai-credits 或 user-rate-limit;两者都会在预算耗尽时跳过 Agent
用了 staged: true 却没效果该字段只见于首页说明,frontmatter 参考页未收录;先 gh aw compile 校验,别照抄不确定的键
换引擎后认证失败不同引擎要不同凭据,缺失会导致激活失败;先按 Authentication 文档配好再切 engine
从别处 gh aw add 的工作流行为异常它的触发条件与安全输出是按原仓库设计的;加 @v1.0.0 固定版本,并逐项改造后再启用
升级后大量文件被改gh aw upgrade 会跑 codemod 并重编译;先 git diff -- .github/workflows/ 审阅再提交
📌 配套阅读:本中心《GitHub MCP server 2.2.0 升级实操》讲的是把仓库能力接进本地 Agent,本篇讲的是让 Agent 在 Actions 里按声明权限动手;两者可以叠加——用 MCP 在本地调好提示词,再搬进 gh-aw 工作流。
← 返回教程中心