创建GitHub代理工作流

构建根据存储库需求定制的自定义 AI 支持的自动化。

在本文中

注意

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

关于创建 GitHub代理工作流

可以使用编码代理（建议）或手动创建 GitHub代理工作流 。 工作流是位于 .github/workflows/ 中的一个 Markdown 文件，其中包含用于配置的 YAML 前置元数据以及面向 AI 代理的自然语言指令。

若要创建代理式工作流，请先在 Markdown 中定义该工作流，将其编译为 .lock.yml 文件，提交这两个文件，然后通过 GitHub Actions 触发器或 GitHub CLI 运行它。

本文重点介绍核心任务：创建、更新和重用工作流。 有关完整的技术详细信息和其他模式，请使用 GitHub代理工作流 文档网站。

Prerequisites

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

  • AI 帐户：GitHub Copilot、Anthropic Claude、OpenAI Codex 或 Google Gemini

  • GitHub具有写入访问权限的存储库

  • GitHub Actions 已为存储库启用

  • GitHub CLI（gh）已安装 v2.0.0 或更高版本，并已通过身份验证

    若要检查版本，请运行 gh --version。 若要进行身份验证，请运行：

    gh auth login --scopes repo,workflow

  • 为 GitHub代理工作流 安装的 GitHub CLI 扩展：

    gh extension install github/gh-aw

    如果使用 GitHub CLI 版本 2.90.0 或更高版本，则运行任何 gh aw 命令将提示你自动安装扩展（如果尚未安装）。

Authentication

可以通过两种方式使用所选的 AI 引擎（编码代理）设置身份验证：

使用内置的 GITHUB_TOKEN

提示

如果你在组织拥有的仓库中使用 GitHub Copilot，强烈建议采用本节中的内置 GITHUB_TOKEN 方法。

如果您在组织拥有的存储库中使用 GitHub Copilot，则可以使用 GitHub Actions 的内置 GITHUB_TOKEN，而不是 personal access token。 这会将该工作流的使用量直接计费到您的组织，并避免管理用于 Copilot 请求的 personal access token 机密。 要进行设置：

  1. 如果尚未启用，您的组织管理员应在 Copilot 设置中启用“允许使用向组织计费的 Copilot CLI”策略。
  2. 对于要向组织计费的工作流，请在工作流的 frontmatter 中添加 copilot-requests: write``permissions。

启用组织计费

必须在 GitHub Copilot 策略设置中启用“允许使用向组织计费的 Copilot CLI”。 如果已启用“Copilot CLI”策略，则默认启用计费策略。

  1. 在 GitHub 的右上角，单击个人资料图片，然后单击“ Your organizations”****。

  2. 单击以选择一个组织。

  3. 在组织名称下，单击 “Settings”****。 如果看不到“设置”选项卡，请选择“”下拉菜单，然后单击“设置”********。

    组织配置文件中选项卡的屏幕截图。 “设置”选项卡以深橙色标出。

  4. 在边栏中，单击 Copilot，然后单击“ 策略”。

  5. 启用“Copilot CLI”，然后启用“允许使用向组织计费的 Copilot CLI”。

向组织计费工作流

创建工作流时，必须在工作流 frontmatter 中的 permissions 下包含 copilot-requests: write。 设置此权限后，Copilot 请求将使用 GitHub Actions' 令牌，对于这些请求，COPILOT_GITHUB_TOKEN 将被忽略。 如果 GitHub Actions 令牌没有来自组织的 GitHub Copilot 访问权限，则工作流在发送 Copilot 请求时会失败，因此应改为配置 COPILOT_GITHUB_TOKEN。

permissions:
  contents: read
  copilot-requests: write

使用 personal access token 或 API 密钥

对于个人存储库或第三方 AI 引擎，你需要创建一个用于存储 personal access token 或 API 密钥的存储库机密。 对于 GitHub Copilot，密钥是 COPILOT_GITHUB_TOKEN，它存储细粒度的 personal access token。

如果使用 gh aw add-wizard，安装流会提示你创建该机密。 如果你要从 GitHub 网页界面创建智能体工作流，或手动创建，则首先需要自行将该密钥添加到仓库的 GitHub Actions secrets 中，可以在 GitHub UI 中进行，或通过 CLI 中的 gh aw secrets set 完成。 有关说明，请参阅 身份验证参考。

创建工作流

建议创建 代理工作流 方法是使用 CLI 编码代理或 VS Code。 这为你提供了一个指导路径，用于创作、编译和提交工作流。

使用 CLI 编码代理或 VS Code

  1. 使用 GitHub CLIGitHub代理工作流 扩展（gh aw）初始化用于智能体创作的存储库（建议在存储库中首次设置时使用）：

    gh aw init

    这会添加与代理工作流创作相关的技能、说明和自定义代理，以便编码代理可以更有效地创建和编辑工作流。

  2. 在你的代码库环境中启动代码代理（例如，Copilot 命令行界面（CLI） 或 VS Code 代理模式）。

  3. 输入一个提及 agentic-workflows 技能并描述你想要的工作流程的提示词：

    Copilot prompt
    /agentic-workflows Create a new workflow that creates a daily report on
recent activity in the repository, delivered as
an issue.

  4. 智能体将创建工作流，并使用 GitHub CLI 编译该工作流。

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

  6. 从 GitHub Actions 选项卡触发工作流，或使用 GitHub CLI 运行：

    gh aw run YOUR-WORKFLOW-NAME

其他创建方法

还可以创建代理工作流：

工作流结构参考

每个工作流 Markdown 文件都有两个部分：

SectionPurpose
YAML frontmatter定义触发器（on）、权限、安全输出和 AI 引擎。
Markdown 正文运行工作流时，AI 代理会遵循自然语言说明。

关键前置信息字段：

领域Description
on事件触发器（其语法与 GitHub Actions 触发器相同）。
permissions已向代理授予仓库权限。 默认值为 read-all.
safe-outputs允许代理执行的写入操作（例如， create-issue， add-comment， create-pull-request）。
engine要使用的 AI 引擎（copilot是默认值;claude``codex，也gemini受支持）。

有关 frontmatter 的完整参考，请参阅 GitHub代理工作流frontmatter 文档。

示例代理工作流

以下示例是某个存储库的简化每周议题活动报告。

---
on: weekly on monday

permissions:
  issues: read
  copilot-requests: write

network: defaults

tools:
  github:
    toolsets: [issues]

safe-outputs:
  create-issue:

---

# Weekly issue activity report

Review issue activity from the last 7 days in this repository.

Create a GitHub issue that includes:

- Total issues opened and closed this week.
- The top recurring themes from issue titles and descriptions.
- A short list of notable issues that still need attention.
- Two or three actionable recommendations for maintainers.

Keep the report concise and action-oriented.

更新工作流

若要更新现有工作流，请执行以下操作：

  1. 在 .github/workflows/ 中编辑工作流 Markdown 文件。

  2. 重新编译以刷新锁定文件：

    gh aw compile

  3. 提交并推送已更新的两个文件。

  4. 打开拉取请求并验证 GitHub Actions 检查项。

有关详细的编辑指南，请参阅 “编辑工作流”。

重用工作流

还可以从可以访问的外部存储库导入工作流。 例如，您可以从 githubnext/agentics 添加一个工作流：

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

对于非交互式设置，可以使用 gh aw add 和选择性地固定版本。

导入工作流时，GitHub CLI 会在 frontmatter 中存储一个 source: 值，以便你稍后可以使用 gh aw update 从上游更新。

仅从你信任的源导入工作流，并在将工作流添加到存储库之前查看工作流的作用。 标记 private: true 的工作流无法导入到其他存储库中。

更新导入的工作流时， GitHub CLI 尝试保留本地更改。 如果存在合并冲突，请解决这些问题，然后再次运行 gh aw compile 。

有关详细信息，请参阅 “重用工作流”。

后续步骤