GitHub 代理式工作流：上手与四道护栏

从装扩展、跑通第一个工作流，到把写权限、出网、裁决与预算收成四道护栏，一条可照做的配置路径。

这篇教程解决什么

GitHub Agentic Workflows 在 2026 年 10 月 28 日转正式可用。它要做的事一句话能说清：用 Markdown 写清「什么时候、对什么、做什么」，编译成标准 GitHub Actions 跑起来。 但它真正难的地方不在写 Markdown，而在「怎么让它别闯祸」——代理会读仓库内容、会调工具、会尝试改东西，默认的宽松配置在生产仓库里是不能用的。

这篇教程给一条完整路径：从装 CLI 扩展开始，跑通官方示例，然后把权限、出网、裁决、预算四件事逐层收紧。照着做，一小时内能拿到一个「只在白名单范围内动手、动作有限额、跑超预算会自己停」的工作流。

读完能得到什么：一个在你自己仓库里真实跑通的代理式工作流，以及一套可以复制到其他工作流的护栏模板。

不覆盖什么：不覆盖自建 AI 引擎的实现细节；不覆盖 GitHub Enterprise Server（当前 AI 应用代码扫描等功能在 GHES 上不可用，代理式工作流本身也以 github.com 为准）；不覆盖复杂多仓编排。文中出现的命令与字段名以官方文档当期版本为准，版本迭代较快，动手前先对一遍文档。

开始前的准备

账号与权限。需要仓库的写权限，并在仓库设置里确认 Actions 已启用。工作流本身是 Actions，所以它继承你已有的 runner 组与策略约束——这一点决定了它比另建一套自动化平台更容易过审。

CLI。GitHub CLI 需要 2.0.0 以上（用 gh --version 确认），并已登录：gh auth login --scopes repo,workflow。少了 workflow 这个 scope，后面写工作流文件会失败。

AI 引擎。官方支持 GitHub Copilot、Anthropic Claude、OpenAI Codex、Google Gemini 与 Pi。有 Copilot 订阅的话可以直接用，不需要额外账号；选其他引擎则要把密钥写成仓库 secret。命令形如 gh secret set ANTHROPIC_API_KEY < 密钥文件。Anthropic 还支持用 Workload Identity Federation 做免密钥交换，适合不想在仓库里长期存密钥的团队。

系统。Linux、macOS，或 Windows 上的 WSL。

预算这项要先想清楚。代理式工作流按 AI credits 计费，跑得多花得多，而且一次运行可能触发多轮模型调用。官方提供了 gh aw forecast 来预估支出，后面护栏那一步会用到。

步骤详解

第 1 步：装 CLI 扩展

在仓库根目录执行：

gh extension install github/gh-aw

如果遇到认证问题，官方给了一条备选安装脚本；也可以先 gh auth login 交互式登录再重试。

成功标志：gh aw --help 能列出子命令。列不出来说明扩展没装到当前用户的 gh 环境里，先确认 gh extension list 里有没有它。

第 2 步：用向导拉一个现成工作流

不要从零写。先用官方示例把链路跑通，再改成自己要的：

gh aw add-wizard githubnext/agentics/repo-status

向导会依次做五件事：检查仓库权限、选择 AI 引擎、配置引擎鉴权、把工作流写进 .github/workflows/（一个 .md 源文件加一个生成的 .lock.yml）、最后问你愿不愿意立刻跑一次。

这一步的关键认知是：你写的是 Markdown，跑的是编译产物。.md 里顶部两行 --- 之间是 YAML frontmatter（触发器、权限、工具、网络、安全输出都在这里），下面是自然语言的任务描述。系统把两者一起编译成标准 Actions YAML。

成功标志：.github/workflows/ 下同时出现 repo-status.md 与 repo-status.lock.yml。只出现前者说明编译没跑，工作流不会生效。

第 3 步：确认它真的跑起来了

一次运行通常两三分钟。看进度有两种方式：网页上打开 Actions 标签页选最近一次运行；命令行用 gh aw status 看工作流状态，或用 gh run watch 跟一次实时日志。

成功标志：Issues 里出现一份由它开出来的仓库状态报告。报告内容应当覆盖最近的 issue、PR、discussion、release 与代码改动，并给出建议的下一步。

如果失败，先看失败在哪一段：预激活阶段失败多半是权限或触发条件不匹配；代理阶段失败多半是引擎鉴权没配好；安全输出阶段失败则是输出没通过校验——这三种失败的排查方向完全不同，别混在一起看。

第 4 步：读懂生成的两个文件

打开 .md，你会看到四块东西，它们决定了后面所有护栏怎么加：

• on：触发条件，用的是标准 Actions 语法，额外支持截止时间、人工审批、fork 处理、按 actor 过滤等。
• permissions：权限声明，级别是 read / write / none，另有 copilot-requests、id-token 这类只写作用域。
• tools：代理能用什么。可以是限定参数的 bash 命令白名单，也可以是 GitHub API 的工具集、MCP 服务器。
• safe-outputs：允许它请求哪些「对外动作」，以及每个动作的上限。

改完 .md 的 frontmatter 之后，必须重新编译：gh aw compile。然后把 .md 与重新生成的 .lock.yml 一起提交——这一步很多人会漏，只提交 Markdown，Actions 读不到更新后的锁文件。

成功标志：gh aw compile 无报错，且 .lock.yml 的修改时间更新。编译期会做 schema 校验、表达式白名单检查、Action 的 SHA 固定，严格模式（默认开启）下还会禁止写权限与通配域名。

第 5 步：第一道护栏——把写权限收进 safe-outputs

这是整套设计里最值得学的一点：代理任务本身没有写权限。它以只读身份跑，所有「建 issue、发评论、提 PR」都只是把请求写成产物，等代理结束后由另一个独立、最小权限、经过校验的任务去执行。

所以你要做的不是「给它写权限」，而是「声明它允许请求哪些动作、各几次」。例如只允许开一个 issue、最多三条评论：

safe-outputs: 段里写 create-issue 的 max 设为 1，add-comment 的 max 设为 3 并配 max-links（代理输出里 URL 出现次数的上限，默认 50）。

几个细节值得记住：不写 safe-outputs 时，系统会保守地自动启用 create-issue，上限 1，并给标题加工作流 ID 前缀；多数输出类型默认上限就是 1，只有 PR 评审评论、关闭 PR 这类默认 10；issue 正文有最短长度限制，占位内容会被拒。

成功标志：故意让代理多请求一次（比如让它开两个 issue），运行不会失败，但第二个请求会被拦下，日志里能看到超出上限的说明。

第 6 步：第二道护栏——把出网收成白名单

代理在容器里跑，容器被绑定到专用网络，HTTP/HTTPS 流量经代理按域名白名单放行。frontmatter 里的 network.allowed 就是这个白名单：可以引用生态标识符（比如 Python/PyPI 这类预置集合），也可以只写死具体域名。

做法上，先按任务需要列最小集合，跑一次看它卡在哪，再逐个补。反过来做——先把大半个互联网放进去再收——等于护栏没装。

成功标志：把某个不在白名单里的域名写进任务里让它访问，请求被拒绝，且日志明确指出被代理拦下。这一条验证的是「出网确实受控」，不是「代理很听话」。

第 7 步：第三道护栏——把威胁检测从提示改成裁决

代理跑完之后，会有一个独立的检测任务把产物（输出 JSON、补丁、提示词）拉下来做分析：查密钥泄漏、查恶意补丁、查策略违规。它没有写权限，也拿不到原代理的运行状态，所以即使代理被污染，裁决这一环仍然是干净的。

默认是 warn 模式：可疑产物被标注，分支推送会转成待审的 PR，不可审查的动作直接中止。要更严就把它设成严格模式，让不通过裁决的输出全部阻断。

这里有一个反直觉但必须记住的点：检测失败或结果无效，等于没有安全裁决，不等于干净。 所以运维上要盯「检测任务本身有没有跑成功」，而不只是看「代理有没有报错」。

成功标志：在测试仓库里故意让代理尝试写一个明显的密钥样式字符串，看检测任务是否标记出来、以及后续动作是否被降级或阻断。

第 8 步：第四道护栏——给预算和次数装上闸门

前七步解决「它能做什么」，这一步解决「它做多少」。frontmatter 里有几组直接可用的限制：max-turns 限制单次运行的轮次，max-ai-credits 与 max-daily-ai-credits 限制单次与每日的额度消耗，user-rate-limit 按窗口限制触发次数，并能忽略特定角色。

配合 gh aw forecast 先预估一次运行的支出区间（GA 版本已把威胁检测的消耗也纳入预估），再据此定额度。先估后限，而不是先跑后看账单。

成功标志：把 max-turns 设成一个明显偏小的值，跑一次，工作流应当在轮次用尽时正常结束而不是报错崩溃，且日志里能看到轮次上限生效。

常见坑与排错

只提交 .md，忘了 .lock.yml。症状是改了任务描述但行为完全没变。锁文件是 Actions 真正执行的文件，必须一起提交；官方特别说明这是有意为之，不是把产物误提交。

用 pull_request_target 又把 head 代码检出。这是官方明确警告的配置：pull_request_target 在基仓库的权限上下文里运行，检出并执行 PR 的 head 代码等于把密钥与写权限暴露给外部提交。优先用 pull_request；确实需要 pull_request_target 且不需要本地检出时，把它设成 checkout: false。

拿 Claude 订阅的 OAuth token 当 API key 用。CLI 会直接检测到并报错，因为订阅令牌不被支持。要用 ANTHROPIC_API_KEY，或配 Workload Identity Federation。

以为「有威胁检测」就等于「已通过」。默认是 warn 模式，产物会被标注而不是阻断。要让不通过的输出停下来，得显式改成严格模式，并且接受它会挡掉一部分本来可用的结果。

用 strict: false 编译。严格模式默认开启，关掉之后工作流在公开仓库里无法运行——运行时才失败，排查起来很绕。团队里如果有多个仓库，可以在 .github/workflows/aw.json 顶层把 strict 固定为 true，避免有人为了图省事关掉。

把「只读令牌」当成「没有其他凭据」。只读的 GITHUB_TOKEN 只约束 GitHub API。自己加进工作流的自定义步骤、setup/post 步骤属于受信任代码，不在沙箱约束内，它们碰到的任何密钥都算你放进去的。

进阶用法

按工作流选引擎与模型。engine 可以逐个工作流指定，不必全仓统一。GA 版本还提供了模型路由（实验性）：给定目标是成本还是成本与速度兼顾，再选 economy / balanced / robust / auto 其中一种模式，具体模型名可用 allowed-models 锁定。适合「例行分诊用便宜档、发布说明用高档」这种分层。

换更硬的隔离。默认跑在 Docker 容器里，也支持 Actions Runner Controller 的 DinD 模式（runner 保持非特权），以及 Cloud Hypervisor 微虚拟机预览。隔离越硬，启动开销越大，按仓库敏感度挑。

接自己的可观测后端。frontmatter 的 observability.otlp 能把运行的追踪与指标发到 OTLP 端点，做法与一般的代理可观测接入一致，可参考站内那篇 Agent 追踪接 OTLP 的配置思路。

先用现成模板铺开。GitHub Next 的 agentics 仓库里有分诊、依赖管理、代码审查、报告等预制工作流，先跑模板再改，比从空文件写快得多。

常见问题

它和普通的 GitHub Actions 有什么不同？

执行载体是同一种东西，产物就是标准 Actions YAML，所以 runner、策略、组织级约束都能复用。差别在「谁决定下一步」：普通 Actions 走的是你写死的步骤，代理式工作流的步骤由模型按任务描述现场决定，因此才需要 safe-outputs、出网白名单、威胁检测这些额外的约束层。

一定要有 Copilot 订阅吗？

用默认的 Copilot CLI 引擎时需要 Copilot 许可。也可以换成 Anthropic、OpenAI、Google 的引擎，或自带编码代理；但换引擎只改变推理来源，不改变权限模型——护栏该配的还是要配。

代理会不会自己把代码合进主干？

默认不会。它的写操作全部走 safe-outputs，由独立任务执行，而且合并类输出在文档里被标为实验性、默认上限很低。真要放开自动合并，建议先在小仓库跑一段时间，把「哪些路径允许自动合」用规则收窄。

检测任务说没问题，是不是就安全了？

不是。检测是分类判断，不是证明；而且它的默认模式只标注不阻断。更重要的是，检测任务本身失败或返回无效结果时，等于没有裁决——这种情况要按「未通过」处理，而不是按「干净」处理。

小团队值得上手吗？

值得的场景很具体：仓库里有一类反复出现、又需要读上下文才能判断的活（issue 分诊、CI 失败归因、文档与代码不一致）。如果只是「定时跑个脚本」，普通 Actions 更省事。判断标准是这件事要不要「读一遍再决定」，不需要就别引入代理。

相关工具与内容

相关工具：GitHub Copilot、Claude Code、Cursor、CodeBuddy。分类入口：编程、智能体。延伸阅读：GitHub Agentic Workflows 正式可用、AI 代码评审的三层闸门、单循环还是多子智能体、给智能体配自主权契约。