关于GitHub代理工作流

在 GitHub Actions 中，使用由 AI 编码代理执行的自然语言指令，自动处理代码仓库中的重复性工作。

在本文中

注意

GitHub代理工作流 are in 公开预览 and subject to change.

关于 代理工作流

GitHub代理工作流 是使用 AI 支持的存储库自动化，可在 Markdown 中定义并作为 GitHub Actions 工作流运行。 与依赖固定 if-then 规则的传统自动化不同，代理工作流 使用代码代理来理解上下文、做出决策并执行有意义的操作——这一切都基于自然语言指令完成。

实际上，与执行预定义步骤的传统工作流相比：

  • 代理工作流 使用上下文推理执行自然语言指令。
  • 你仍然在 frontmatter 中定义护栏，例如触发器、权限和安全输出。

使用 代理工作流，可以自动执行如下任务：

  • 对传入问题进行分类，并按类型和优先级对其进行标记
  • 调查 CI 失败问题并提出修复建议
  • 生成每日或每周存储库状态报告
  • 使文档与代码变更保持同步
  • 改进测试覆盖率

使用代理工作流的好处

  • 自动执行重复存储库工作。 以自然语言定义问题会审、CI 调查、文档更新和报告。
  • 降低工作流复杂性。 编写 markdown 指令，而不是为每个方案生成复杂的过程脚本。
  • 在循环中保持人工评审。 代理工作流 可以生成可直接审核的内容，例如议题、评论和拉取请求，而审批和合并则由你来控制。
  • 使用分层安全性运行代理。 默认情况下，代理在具有只读令牌的防火墙容器中运行。 写入操作仅限于你已定义并声明为“安全输出”的内容，且需经过智能体威胁检测检查。

要求

若要创建和使用 代理工作流，需要：

  • GitHub Actions 已为您的存储库启用。
  • 具有 AI 引擎（代理）的帐户，例如GitHub Copilot，Anthropic ClaudeOpenAI Codex或 Google Gemini。
  • GitHub CLI 已安装并经过身份验证

工作原理代理工作流

每个工作流 Markdown 文件由两部分组成：

  • Frontmatter（位于 --- 标记之间的 YAML）：配置工作流何时运行、它具有哪些权限，以及允许执行哪些写入操作。
  • Markdown 正文：包含 AI 代理遵循的自然语言指令。

概括而言，创建和使用 代理工作流 的过程是：

  1. 定义代理工作流 .md 文件，包括 YAML frontmatter 和 Markdown 指令。
  2. 将 markdown 工作流文件编译为强化的 .lock.ymlGitHub Actions 工作流文件。
  3. 提交这两个文件并将其推送到存储库的默认分支。
  4. 像运行任何其他 GitHub Actions 工作流一样，在存储库的触发器或 Web 界面上运行 GitHub 工作流。 你也可以从GitHub CLI运行它。

下面是为存储库创建每日状态报告问题的工作流示例：

---
on: daily

permissions:
  contents: read
  issues: read
  pull-requests: read
  copilot-requests: write

network: defaults

tools:
  github:
    toolsets: [default]

safe-outputs:
  create-issue:

---

# Daily Repo Status Report

Review recent activity in the repository, including issues, pull requests, discussions, and code changes.

Create a GitHub issue summarizing what changed in the last 24 hours (merged pull requests, closed issues, and new discussions), any blockers or open questions mentioned in comments, progress toward visible goals, and recommended next steps for maintainers.

Keep the summary concise. Adjust the level of detail based on how much activity occurred.

有关创建和更新 代理工作流的详细步骤，请参阅 创建GitHub代理工作流。

支持的编码代理

GitHub代理工作流 支持多个编码代理，包括：

  • GitHub Copilot （需要 GitHub Copilot 计划）
  • Anthropic Claude
  • OpenAI Codex
  • 谷歌双子座

您可以在工作流 frontmatter 属性 engine 中指定要使用的智能体。 每个引擎都需要在存储库中配置自己的身份验证机密。 GitHub Copilot 如果未指定任何引擎，则为默认引擎。

有关详细信息，请参阅 引擎参考。

安全防护措施

GitHub代理工作流 在设计时将安全性放在首位：

  • 默认情况下，只读：除非显式授予更多权限，否则工作流具有只读存储库权限。
  • 安全输出：写入操作（如创建议题、添加评论或发起拉取请求）仅允许通过在 frontmatter 中声明的经 safe-outputs 验证的内容进行。
  • 机密保留在代理运行时之外：敏感凭据保存在隔离的下游作业中，而不是直接公开给代理。
  • 威胁检测：在执行写入操作前，会对拟议的输出内容进行扫描，以检测可疑或不安全的更改。
  • 防火墙执行：代理在隔离 GitHub Actions 环境中运行。
  • 基于角色的访问：可以限制谁可以使用基于角色的访问控制触发或修改 代理工作流 。

有关完整的体系结构演练，请参阅 安全文档。

使用情况和计费

代理工作流 的总成本包括两个部分：

  • GitHub Actions 工作流作业消耗的分钟数。
  • 配置的 AI 引擎的推理成本。

对于推理任务，GitHub代理工作流 使用 AI 积分（AIC）作为跨引擎监控和预算的通用指标。 1 AIC = $0.01 USD。

具体如何计费取决于引擎：

  • 默认 GitHub Copilot 引擎：AIC 使用量在 AI credits 计费中映射为 GitHub Copilot。
  • 第三方引擎：推理费用由该服务提供商计费。

您可以使用 GitHub CLI 查看 代理工作流 的使用情况和预估成本。 使用 gh aw logs 查看最近的工作流运行记录，包括各次运行的持续时间、令牌使用情况和 AIC 估计。 使用 gh aw audit RUN-ID 可更详细地检查单次运行，包括令牌用量和预估的推理成本。 AIC 值是最佳努力估算值，可能与提供商发票不完全匹配，因此请在提供商的计费仪表板中验证最终费用。

你还可以在工作流前置元数据中设置 max-ai-credits，以限制单次运行的推理使用量上限。 每次运行的默认上限为 1,000 AIC。

有关计费GitHub代理工作流和成本优化指南的概述，请参阅文档网站上的成本管理GitHub代理工作流。

为 GitHub代理工作流 启用组织计费

对于组织拥有的仓库中的 GitHub Copilot 代理工作流，如果该组织采用 GitHub Copilot 计划，我们强烈建议使用 GitHub Actions 内置的 GITHUB_TOKEN。 此方法向组织计费，并避免使用 personal access token.

若要向组织计费，需要：

  1. 组织管理员在 GitHub Copilot 策略设置中启用“Copilot CLI”和“允许使用向组织计费的 Copilot CLI”。 如果已启用“Copilot CLI”，则默认启用计费策略。
  2. 在每个工作流的 frontmatter 中，在 permissions 对象下包含 copilot-requests: write。

当在工作流的 frontmatter 权限设置中设置 copilot-requests: write 时，Copilot 请求将使用 GitHub Actions 令牌，因此无需 COPILOT_GITHUB_TOKEN。 如果 GitHub Actions 令牌没有来自组织的 GitHub Copilot 访问权限，则工作流在发送 Copilot 请求时会失败，因此应改为配置 COPILOT_GITHUB_TOKEN。

有关详细的设置说明，请参阅 “使用内置 GITHUB_TOKEN”。

后续步骤