GitHub Agentic Workflows 上手：用 Markdown 写仓库 AI 自动化，管住写权限和费用
按 gh-aw 官方文档（v1.0.1 实测）：装好 gh aw 扩展并初始化仓库，用 Markdown 加 YAML 写仓库周报和 Issue 分诊两个工作流，编译成 GitHub Actions；用 safe outputs 白名单和严格模式管住 AI 的写操作，用 staged 先预览；再配置 Copilot 或 Claude 等引擎认证，设好 max-ai-credits 费用上限，触发运行并用 logs、audit、forecast 看花费。
入门·3 课时·65 分钟·图文实操
免费学习无需登录
你将学会
- 装好 gh-aw 并初始化仓库
- 用 Markdown 写 AI 工作流
- 编译生成 lock.yml
- 用 safe outputs 限定写操作
- 用 staged 模式预览
- 设置 AI 费用上限
适合谁
- 开源项目维护者
- 在用 GitHub Actions 的开发者
- 要管控 AI 权限和花费的团队
课前准备
- 会用 Git 和终端
- 装好 GitHub CLI 并能登录
- 有 Copilot 或任一家 AI 的 API Key
课程目录
3 课时 · 65 分钟- 01装好 gh-aw，写出并编译第一个工作流检查 gh 版本与登录权限，用 gh extension install 装好 gh-aw v1.0.1，用 gh aw init 初始化仓库，手写一个按周运行、只读权限、只允许创建 1 个 Issue 的仓库周报工作流，用 gh aw compile 生成 lock.yml 并看懂 activation、agent、detection、safe_outputs 几个作业的分工。图文20 分钟开始本课
- 02Issue 分诊工作流：触发器、safe outputs 与 staged 预览按官方图库示例写一个新开 Issue 就自动运行的分诊工作流，用 add-labels 白名单和 add-comment 次数限定 AI 的写操作，故意改成 issues: write 看严格模式如何拒绝，从 lock 文件里确认代理拿到的工具，再用 staged: true 只预览不落地。图文20 分钟开始本课
- 03推到 GitHub 跑起来：认证、费用上限、日志与换引擎用 COPILOT_GITHUB_TOKEN 或各家 API Key 配置引擎认证，用 max-ai-credits、max-turns、skip-if-match 控制费用，推送后用 gh aw run --dry-run 校验、gh aw run 触发、gh aw status 看状态，用 logs、audit、forecast 查耗时与 AIC 花费，最后用 -e图文25 分钟开始本课
课程说明
GitHub Agentic Workflows（命令行里叫 gh-aw）是 GitHub Next 开源的仓库自动化工具，2026 年 10 月 28 日正式 GA。你用 Markdown 写一段自然语言指令，再在文件开头的 YAML 里写好触发条件和权限，gh aw compile 就会把它编译成标准的 GitHub Actions 工作流，在 Actions 里让 GitHub Copilot、Claude Code、OpenAI Codex 或 Gemini 等编程代理去做 Issue 分诊、仓库周报、CI 失败分析这类需要「理解内容」的活。代理默认只有读权限，所有写操作都要通过 safe outputs 声明，并先经过威胁检测。
本课按 gh-aw 官方文档（https://github.github.com/gh-aw/ ）和官方示例仓库整理。2026-10-31 在一台 Linux 云主机上用 gh 2.103.0 和 gh-aw v1.0.1 逐条实跑了安装、初始化、编写、编译、严格模式报错、staged 模式、费用上限和 run --dry-run，「对照结果」都是真实输出。真正在 GitHub 上运行、看日志和花费需要登录并配置 AI 账号，这部分按官方文档整理，课内会单独注明。全课共 3 课时：
| 课时 | 你会做完的事 | 需要什么 |
|---|---|---|
| 1 | 装好 gh-aw，初始化仓库，手写一个仓库周报工作流并编译 | 终端，gh 已登录 |
| 2 | 写 Issue 分诊工作流，用 safe outputs 限定写操作，用 staged 预览 | 同上 |
| 3 | 配置 AI 认证、费用上限，触发运行，看日志与花费 | 同上，另需 AI 账号 |
适合
- 想让 AI 自动分诊 Issue、写仓库周报的开源维护者
- 已经在用 GitHub Actions、想加入 AI 步骤的开发者
- 想控制 AI 代理权限和花费的团队负责人
先修
- 会用 Git 和终端，有一个自己有写权限的 GitHub 仓库
- 装好 GitHub CLI（gh 2.0 以上）并能登录
- 有 GitHub Copilot，或 Anthropic、OpenAI、Google 任一家的 API Key（第 3 课真正运行时需要）
你会学到
- 用
gh extension install github/gh-aw安装，用gh aw init初始化仓库 - 看懂工作流文件的 frontmatter 和 Markdown 正文分别管什么
- 用
gh aw compile生成.lock.yml，认识 activation、agent、detection、safe_outputs 作业 - 用
safe-outputs白名单限定代理能加的标签和评论数，理解严格模式为什么拒绝写权限 - 用
staged: true预览、用max-ai-credits、max-turns、skip-if-match控制费用 - 用
gh aw run、status、logs、audit、forecast运行和复盘，用engine:换引擎
官方资料
- 官方文档首页：https://github.github.com/gh-aw/
- Quickstart：https://github.github.com/gh-aw/setup/quick-start/
- 创建工作流：https://github.github.com/gh-aw/setup/creating-workflows/
- CLI 命令：https://github.github.com/gh-aw/setup/cli/
- Safe Outputs：https://github.github.com/gh-aw/reference/safe-outputs/
- Staged Mode：https://github.github.com/gh-aw/reference/staged-mode/
- 费用管理：https://github.github.com/gh-aw/reference/cost-management/
- 认证：https://github.github.com/gh-aw/reference/auth/
- Issue 分诊示例：https://github.github.com/gh-aw/gallery/ai-issue-triage/
- 官方示例仓库：https://github.com/githubnext/agentics
- 源码仓库：https://github.com/github/gh-aw
- GA 公告：https://github.blog/changelog/2026-10-28-github-agentic-workflows-generally-available/
绑定工具： GitHub Agentic Workflows（/tools/github-agentic-workflows/）