代理如何与GitHub API 和工作流进行交互

  • 5 分钟

AI 代理正在更改开发工作完成方式。 代理可以直接在GitHub内操作，而不是手动导航存储库、编写代码和运行命令，以从头到尾完成任务。

GitHub支持通过多个层执行代理驱动的工作。 代理可以使用 GitHub API 读取存储库状态和执行操作，GitHub Actions工作流在受控运行程序中执行自动化，GitHub Agentic Workflows 来描述 Markdown 中的更高级别的存储库任务，并在强防护措施下使用编码代理运行它们。 代理无需绕过GitHub，而是使用与开发人员相同的系统，包括分支、拉取请求、问题和自动化。

在本单元中，你将了解：

  • 代理如何通过 API 与GitHub交互
  • 代理如何将工作流用作执行环境
  • 如何创建和管理存储库更改
  • GitHub上的完整代理执行流的外观

代理如何与GitHub交互

GitHub代理（例如Copilot云代理）在定义的存储库和分支上下文中运行。 分配任务（例如通过问题或提示）时，代理将开始在该存储库中工作。

代理可以：

  • 研究并了解存储库
  • 规划完成任务所需的更改
  • 在新分支上更改代码
  • 打开拉取请求以供审阅

代理使用 GitHub 平台功能（如 API 和工作流）执行这些操作。

这些操作可由存储库事件（如推送或拉取请求）触发，也可以按计划运行，或通过代理工作流进行协调，这些工作流会随着时间的推移持续自动执行存储库任务。

使用 GitHub API 执行操作

GitHub提供了允许系统以编程方式与存储库交互的 API。

多个 API 可实现的操作包括：

  • 创建分支和提交
  • 读取存储库数据
  • 打开和更新拉取请求
  • 触发工作流

必须使用个人访问令牌、GitHub应用令牌或工作流中提供的GITHUB_TOKEN等令牌对所有 API 请求进行身份验证。

这可确保代理执行的每个操作都受权限控制且可审核。

代理如何在存储库中创建更改

当代理进行更改时，它会遵循与开发人员相同的工作流。 典型的序列如下所示：

  1. 选择基分支
  2. 创建新的工作分支
  3. 修改或创建文件
  4. 提交更改
  5. 打开拉取请求

每个步骤都有单独的 API 操作，包括使用 Git 引用、存储库内容和拉取请求。

这意味着代理操作与GitHub的标准开发模型完全一致。

使用GitHub Actions作为执行层

代理不会直接在计算机上执行任务。 相反，GitHub通过由GitHub Actions提供支持的工作流提供执行环境。

工作流是 YAML 定义的进程，用于运行作业以响应事件。

代理依赖于以下工作流：

  • 运行测试
  • 验证更改
  • 执行自动化任务
  • 部署应用程序

Copilot云代理在GitHub Actions提供支持的环境中运行，这意味着工作流构成了代理执行的基础。

传统工作流与代理工作流

传统的GitHub Actions工作流通常是确定性的，YAML 定义：显式指定每个步骤、触发器和条件。 GitHub代理工作流为存储库自动化添加其他模型。 它们允许你在 Markdown 中描述所需的结果，在 frontmatter 中定义护栏，并在 GitHub Actions 中使用编码代理执行该意向。 它们最适合开放但受限的存储库任务，例如会审、报告、文档维护、CI 故障分析和代码改进。 它们并没有替换 CI/CD 管道，而是通过 GitHub 所描述的"连续 AI"来扩展这些管道。

是什么使代理工作流不同

GitHub代理工作流有两个主要部分：

  • 用于配置的前置信息，例如触发器、权限、工具和安全输出结果
  • 使用自然语言描述作业的 Markdown 说明

“Markdown” 表示意图，而“前置内容”定义边界。 然后，工作流将被整理成一个供GitHub Actions执行的锁定文件。

on: schedule: daily
permissions: contents: read issues: read pull-requests: read
safe-outputs: create-issue: title-prefix: "[repo-status] " labels: [report]
tools: github:

Daily Repository Status Report
Create a daily report for maintainers.
Include:
Recent activity (issues, PRs, commits)
Key highlights and risks
Recommended next steps
Keep the report concise and link to relevant issues and pull requests.

在此示例中，frontmatter（在 --- 之间）定义工作流的运行方式和时间、可以访问的内容以及允许的操作。

以下 Markdown 使用自然语言定义工作流的意图。 代理解释此意向并生成结构化输出，然后通过受控的可审阅步骤应用这些输出。

与传统GitHub Actions工作流不同，这些工作流明确定义每个步骤，代理工作流侧重于描述结果。 代理确定如何在 frontmatter 中定义的约束内实现目标。

触发和与工作流交互

可以通过多种方式触发工作流：

  • 自动通过推送或拉取请求等事件
  • 手动使用 workflow_dispatch 事件
  • 以编程方式通过 GitHub API

代理可以依赖这些触发器来执行任务，或在对存储库进行更新后验证更改。

每个工作流运行在隔离的环境中执行作业，确保一致且安全执行。

代理会话期间发生的情况

代理会话是可观察且交互式的。

在会话期间，您可以：

  • 通过会话日志监视进度
  • 查看代理正在执行的操作
  • 提供反馈或调整任务
  • 查看最终拉取请求

代理根据反馈进行调整，并继续工作，直到任务完成。

端到端代理执行流

将所有代理放在一起时，与GitHub的典型代理交互如下所示：

  1. 通过问题、聊天或 CLI 分配任务
  2. 代理选择存储库和基分支
  3. 代理分析代码库并计划更改
  4. API 操作用于创建分支并进行提交。
  5. 已创建拉取请求
  6. 工作流运行以验证或部署更改
  7. 用户评审、批准或请求更新

此流可确保所有代理活动为：

  • 范围限定为存储库
  • 由权限控制
  • 通过工作流执行
  • 可见且可查看

关键要点

GitHub上的代理不会在平台外部运行。 它们通过实施权限的 API、工作流和存储库结构进行交互，提供执行环境，并通过拉取请求启用协作。

接下来，你将了解模型上下文协议（MCP）如何通过使代理能够连接到除GitHub以外的其他工具和服务来扩展这些功能。