在 GitHub Actions 中开发代理工作流

用于 GitHub代理工作流 将 Markdown 指令转换为由第三方编码代理提供支持的自动化。

在本文中

注意

GitHub代理工作流 处于其中 公开预览 且可能会更改。

Introduction

GitHub代理工作流 允许在 Markdown 中定义存储库自动化，并选择运行它们的 AI 编码代理。 该 gh aw 扩展将每个代理工作流编译为工作流 GitHub Actions 。

整个工作流生命周期（创作、调试和优化）本身是代理性的。 描述自然语言所需的内容，编码代理会为你创建、优化和排查工作流问题。

本教程使用编码代理创建自动拉取请求审阅者，用于检查更改是否已经过充分测试。

先决条件

在开始之前，请确保具备：

  • 已启用且 GitHub Actions 具有写入访问权限的存储库
  • GitHub CLI 版本 2.0.0 或更高版本已安装并经过身份验证
  • 访问支持的编码代理（例如 Claude Code 或 OpenAI CodexGoogle Gemini CLI，或 Copilot 命令行界面（CLI））及其所需的凭据

若要进行身份验证 GitHub CLI，请运行：

gh auth login --scopes repo,workflow

安装 gh aw 扩展

安装 GitHub代理工作流 以下扩展 GitHub CLI：

gh extension install github/gh-aw

选择代理并配置身份验证

选择最适合工作流的代理 CLI。 Claude Code 或 OpenAI CodexGoogle Gemini CLI，并且 Copilot 命令行界面（CLI） 都可以运行 GitHub代理工作流。

本文逐步讲解将代理凭据添加为存储库机密的简单设置。 如果使用 Claude Code 或 OpenAI CodexGoogle Gemini CLI，请将代理的 API 密钥存储为存储库机密。

| 代理 CLI | engine 值 | 存储库机密 | | --- | --- | --- | | 克劳德密码 | claude | ANTHROPIC_API_KEY包含Anthropic API 密钥 | | OpenAI Codex | codex | OPENAI_API_KEY 包含 OpenAI API 密钥 | | Google Gemini CLI | gemini | GEMINI_API_KEY 包含 Google AI Studio API 密钥 | | Copilot 命令行界面（CLI）（默认值） | copilot | 组织存储库不需要机密（请参阅下文）。 对于个人存储库，COPILOT_GITHUB_TOKEN包含Copilot请求设置为****“读取”的细粒度personal access token。 |

其他引擎（如 Pi（实验性）也受支持。 有关完整列表，请参阅 GitHub代理工作流 身份验证参考。

组织计费 GitHub Copilot

如果在 GitHub Copilot 组织拥有的存储库中使用，则可以使用 GitHub Actions内置 GITHUB_TOKEN 存储库而不是 personal access token内置存储库。 添加到 copilot-requests: write 工作流 frontmatter permissions ，不需要单独的机密。 有关设置步骤，请参阅 创建GitHub代理工作流。

在 GitHub UI 中存储机密

若要为或个人存储库添加机密 Claude Code 或 OpenAI CodexGoogle Gemini CLI， GitHub Copilot 请执行以下操作：

  1. 打开 GitHub，导航到存储库。
  2. 在存储库名称下，单击“ 设置”。
  3. 在边栏中，单击“ 机密”和“变量”，然后单击“ 操作”。
  4. 单击“新建存储库机密”。
  5. 在“ 名称” 字段中，输入上表中的机密名称。
  6. 在 “机密 ”字段中，输入值。
  7. 单击“添加机密”。

创建工作流程

使用编码代理从自然语言说明创建工作流。

  1. 在存储库根目录中，初始化用于代理创作的存储库。 这会添加有助于编码代理创建和编辑工作流的技能和说明：

    gh aw init

  2. 在存储库的上下文中启动编码代理会话，例如，使用Claude Code 或 OpenAI CodexGoogle Gemini CLICopilot 命令行界面（CLI）或 VS Code 代理模式。

  3. agentic-workflows使用技能并描述所需的工作流：

    Copilot prompt
    /agentic-workflows create a pr reviewer that ensure the changes are tested.

    代理在 <a0/> 中创建工作流 Markdown 文件，编译相应的工作流文件，并要求查看并提交这两个文件。

  4. 查看生成的工作流，然后要求代理提交并推送文件。

提示

可以在运行工作流后使用相同的代理方法来更新和改进工作流。 要求代理优化评审条件、添加更多检查或调试失败的运行 ，全部采用自然语言。 如果稍后编辑工作流前端，请在提交更改之前运行 gh aw compile 。

运行工作流

生成的工作流在拉取请求上自动触发，以便在下次打开或更新存储库中的拉取请求时运行。

  1. 在你的存储库中创建一个 Pull Request。
  2. 打开 GitHub，导航到存储库，然后单击“ 操作 ”选项卡。
  3. 在左侧栏中，选择代理创建的工作流。
  4. 运行完成后，工作流将留下拉取请求评审，指出更改是否包含足够的测试。

后续步骤