用Markdown写AI自动化：GitHub Agentic Workflows上手

2026年10月28日，GitHub 宣布 GitHub Agentic Workflows（智能体工作流）正式可用。一句话说清它是什么：你用一份普通的 Markdown 文件，用大白话写下“想让 AI 在仓库里定期做什么”，它就会被编译成标准的 GitHub Actions 工作流，由 Copilot 或你自己选的编码智能体去执行。整理 Issue、分析 CI 为什么挂了、更新文档、补测试，这些以前要人盯着做的“动脑子的杂活”，现在可以交给它按时跑。

这篇文章不讲虚的，带你弄懂它能干嘛、安不安全、10 分钟怎么跑通第一个工作流。

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

普通的 GitHub Actions 是“写死的脚本”：第几步跑什么命令，一行一行写清楚，它只会照做。遇到需要判断的事情，比如“这个 Issue 是 bug 还是功能建议”“这次测试失败是代码问题还是网络抖动”，脚本就无能为力了。

Agentic Workflows 的思路是：流程骨架交给 Actions，需要判断的部分交给 AI 智能体。你写的是一份带配置头的 Markdown：

文件最上面两条 --- 之间是 YAML 配置（叫 frontmatter），写清什么时候触发、用哪个 AI 引擎、有哪些权限。
下面的正文就是自然语言任务说明，比如“汇总过去一天的 Issue 和 PR，挑出需要维护者关注的事项，发一个日报 Issue”。

然后用命令 gh aw compile 把它编译成一个 .lock.yml 文件。两份文件都提交进仓库，GitHub Actions 就会按计划运行。因为本质上还是 Actions，你原来的 Runner、组织策略、权限限制都照样生效。

能用哪些 AI？要花钱吗？

根据官方快速入门文档，目前可选的引擎有 GitHub Copilot、Claude Code、OpenAI Codex、Google Gemini 和 Pi。

官方说它在 GitHub Free、Team、Enterprise 上都可用，但默认的 Copilot CLI 引擎需要 Copilot 授权。
如果用 Claude、OpenAI 或 Gemini，需要你自己的 API Key，存成仓库机密（Secret）。注意：官方明确说用 claude login 得到的订阅令牌不支持，要用 API Key 或身份联合认证。
正式版里 gh aw forecast 预算预估命令已经转正，可以提前估算每月大概要消耗多少 AI 额度，心里有个数再上。

让 AI 进仓库，安全吗？

这是大家最担心的点。官方公告列出了几层防护：

默认只读：智能体默认只有读权限，不能直接改你的代码。
沙箱 + 防火墙：智能体在隔离容器里运行，网络出口受“Agent Workflow Firewall”限制。
安全输出校验：AI 想做的事（比如发评论、开 PR）要先经过“safe outputs”流程检查。
威胁检测：所有拟提交的改动在落地前，会被一个专门的检测任务扫一遍。

正式版还加了更强的隔离选项，比如可以在微型虚拟机里运行，跨仓库时用“enclave”防止数据泄露。另外文档特别提醒：触发方式优先用 pull_request，慎用 pull_request_target，因为后者在主仓库的高权限环境里运行，如果去执行外部 PR 的代码，可能暴露密钥。

10 分钟跑通第一个工作流

下面按官方快速入门整理，目标是在你自己的仓库里装一个“每日仓库状态日报”。

准备工作

一个你有写权限的 GitHub 仓库，并在 Settings 里确认 Actions 已开启。
安装 GitHub CLI（gh，2.0 以上），运行 gh auth status 确认已登录；没登录就运行 gh auth login --scopes repo,workflow。
系统用 Linux、macOS，或 Windows 下的 WSL。
一个 AI 账号：有 Copilot 的话最省事。

第 1 步：安装扩展

gh extension install github/gh-aw

第 2 步：添加示例工作流

在仓库根目录运行：

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

这是官方示例库里的“仓库日报”工作流。向导会一步步带你：检查权限、选择 AI 引擎、配置认证、把 .md 和编译好的 .lock.yml 放进 .github/workflows/（可以直接推送，也可以开 PR），最后可选立即触发一次。

如果选 Copilot 且没有组织统一计费，需要建一个细粒度个人令牌（PAT），在账号权限里把 Copilot Requests 设为 Read，再用 gh secret set COPILOT_GITHUB_TOKEN 存成仓库机密。

第 3 步：等它跑完

一次运行大约 2–3 分钟。可以在仓库的 Actions 页面看，也可以命令行运行 gh aw status 查看状态。成功后，Issues 里会出现一个“Daily Repo Report”，汇总最近的 Issue、PR、发布和代码变化，并给出下一步建议。

第 4 步：改成你自己的需求

打开 .github/workflows/repo-status.md，把“要包含什么”那一段改成你真正头疼的事，比如积压的 Issue、经常失败的 CI、测试覆盖率。如果改了顶部配置，记得重新运行 gh aw compile，然后把两份文件一起提交。想马上再跑一次：

gh aw run repo-status

适合谁用？几个实用场景

个人开源项目维护者：每天自动出一份仓库日报，不用自己翻一堆通知。
小团队：新 Issue 自动打标签、分类，减少人工分拣。
CI 经常红的项目：让智能体先分析失败原因，给出初步结论再找人。
文档跟不上代码的项目：定期检查改动，提出文档更新建议。

官方的 githubnext/agentics 仓库里有现成模板，覆盖分拣、依赖管理、代码审查、报告等，建议先从模板改，比从零写更稳。

小结

GitHub Agentic Workflows 把“会判断的 AI”塞进了大家已经熟悉的 GitHub Actions 里：用 Markdown 写需求，编译成标准工作流，默认只读加多层防护。对普通开发者来说，最值得做的一步就是挑一个示例装进自己的仓库，跑一次，看看 AI 日报能不能帮你省下每天翻通知的时间。用之前记得先用 gh aw forecast 估一下额度消耗。