GitHub Agentic Workflows 进入团队后权限边界怎么设计

团队第一次把 GitHub Agentic Workflows（gh-aw）接进 GitHub Actions，最容易犯的错是把“会分析代码”理解成“应该能直接改仓库”。更稳妥的边界是：Agent 默认只读，修改通过 safe-outputs 交给独立作业，生产分支、发布凭据和跨仓库写入再加 Environment 审批。这样既保留自动化效率，也不会把一次提示注入直接变成仓库写权限。

GitHub Agentic Workflows 到底改变了哪一层

它不是把普通 GitHub Actions 换成一段更长的提示词，而是在 Actions 运行中增加了一个能理解 Markdown 指令的 Agent。工作流通常写在 .github/workflows/*.md，再用 gh aw compile 生成带锁定依赖的 .lock.yml。它目前仍处于 Public Preview，所以团队应把权限和回退方案写进工程约束，而不是只依赖模型“自觉”。

权限上要先分清三层。Agent 作业读取代码、Issue 或 Pull Request，并在沙箱里完成判断；它输出的是结构化请求，不是直接调用 GitHub 写接口；之后的 safe-output 作业才使用受限令牌执行评论、标签或建 PR。GitHub 官方文档还强调，直接给 contents: write 或自定义写作业属于另一条信任边界，不会自动继承 safe-outputs 的全部保护。

最小权限配置怎么落地

以“检查 Pull Request 并在发现问题时留言”为例，先只给读取权限，把输出数量设成小上限。下面的配置是一个可继续收紧的起点：

---
on:
  pull_request:
    types: [opened, synchronize]

permissions:
  contents: read       # 只读取仓库内容
  pull-requests: read  # 只读取 PR 上下文

safe-outputs:
  add-comment:
    max: 1             # 每次运行最多一条汇总评论
  create-pull-request:
    max: 1             # 需要改代码时只允许生成一个 PR
    allowed-files:
      - "docs/**"      # 先把可改范围收窄到文档目录
---

检查变更内容、测试证据和明显的安全风险。
只有发现具体问题时才输出评论；没有问题时明确输出 noop。

这里的关键不是字段多，而是每个动作都有边界：触发事件只监听必要类型，读取权限按资源声明，输出有 max，代码变更还有允许文件范围。工作流加入仓库后，先用 gh aw compile .github/workflows/pr-review.md 生成锁文件，再检查实际生成的权限、工具、网络和 safe-output 作业；frontmatter 改了就必须重新编译。

生产写入为什么还要再加人工闸门

评论和草拟 PR 通常可以自动化，但发布、修改保护分支、操作部署配置、跨仓库写入就不该只靠 safe-output 的默认限制。推荐顺序是 Agent 结果先经过威胁检测，再进入配置了审核人的 Environment，最后才让 safe-output 作业运行。审核人看到的是已经过检测的输出；拒绝时，后续写入作业不会执行。

jobs:
  approval-gate:
    runs-on: ubuntu-latest
    needs: detection
    environment: production-deploy  # 在 Settings → Environments 配置审核人
    steps:
      - name: 记录人工批准
        run: echo "approval granted"  # 只作为闸门，不在这里执行发布

  safe-outputs:
    needs: [approval-gate]            # 审批通过后才允许受限写入

还要留意三个常见误区：仓库密钥不会因为 Agent 运行在 Actions 中就自动安全，显式传入工具或 MCP 的凭据仍需单独审查；开启网络时应使用允许域名清单；如果工作流要处理公共 Issue，需理解 integrity filtering 对低可信内容的过滤规则。安全输出会做密钥脱敏、URL 域名过滤、大小限制和 HTTPS 检查，但直接写权限和自定义作业不自动获得这些保护。

上线前用四个问题检查边界

1. Agent 是否只有完成任务所需的 read 权限？若出现 contents: write，能否说明独立的信任边界和回滚路径？
2. 每个 safe-output 是否配置了目标、文件范围和 max，并且没有用任意 Shell 绕过它？
3. 生产动作是否经过 threat detection 和 Environment 审核？审核是否由 GitHub 平台保护，而不是由提示词要求 Agent 自己“确认”？
4. frontmatter 改动后是否重新编译并检查 .lock.yml，触发器、网络 allowlist 和工具是否仍符合团队策略？

官方资料入口可从 权限参考、safe-outputs 参考 和 FAQ 的 Guardrails 开始。它们比单看生成的 YAML 更能解释为什么“只读 Agent + 受限写入 + 平台审批”是三个不同边界。

相关问题

Agentic Workflows 会取代普通 GitHub Actions 吗？

不会。构建、测试、Lint、部署等可重复步骤仍适合普通 Actions；需要理解上下文、归纳问题或生成建议的任务才适合 Agentic Workflows。

safe-outputs 和直接给写权限有什么区别？

safe-outputs 将写入限定在预定义操作、次数和目标内，并在独立作业中执行；直接写权限或自定义作业由团队自己承担更大的权限和审计责任。

只改 Markdown 正文也要重新编译吗？

正文指令通常在运行时加载；但触发器、权限、工具、网络和 safe-outputs 位于 frontmatter，修改后应重新运行 gh aw compile 并审查 lock 文件。

怎样把人工审批接到安全输出前面？

给自定义闸门作业配置 GitHub Environment protection，并让 safe-outputs 依赖该作业；审核拒绝或闸门失败时，写入作业不会继续。