gh-agent-task

GitHub CLI Agent 任务扩展

gh agent-task 扩展可通过 CLI 创建 GitHub Copilot 编码 Agent 任务。任务是一个 GitHub issue，可根据自然语言指令触发自动代码更改。

仓库：https://github.com/github/agent-task（内部 GitHub 扩展）

概述

Agent 任务是 GitHub issue，可用于：

• 包含代码更改的自然语言指令
• 触发 GitHub Copilot 自主执行任务
• 创建包含已实现更改的拉取请求
• 提供审查和合并自动代码修改的工作流

安装

通过 GitHub CLI 安装：

gh extension install github/agent-task

注意：此扩展需要使用具有创建 issue 和拉取请求所需权限的个人访问令牌（PAT）进行身份验证。

核心命令

创建 Agent 任务

根据描述创建新的 Agent 任务：

# Create task with inline description
gh agent-task create "Fix the bug in authentication flow"

# Create task from file
gh agent-task create --from-file task-description.md

# Specify base branch
gh agent-task create --base develop "Implement new feature"

# Create in different repository
gh agent-task create --repo owner/repo "Update documentation"

命令参数：

• 描述（位置参数）：任务的自然语言描述
• --from-file <path>：从文件读取任务描述
• --base <branch>：拉取请求的基分支（默认：仓库的默认分支）
• --repo <owner/repo>：目标仓库（默认：当前仓库）

输出格式： 该命令会输出已创建 Agent 任务的 URL：

https://github.com/owner/repo/issues/123

列出 Agent 任务

列出仓库中的 Agent 任务：

# List all agent tasks
gh agent-task list

# List with filters
gh agent-task list --state open
gh agent-task list --state closed
gh agent-task list --state all

查看 Agent 任务

查看特定 Agent 任务的详细信息：

# View by number
gh agent-task view 123

# View by URL
gh agent-task view https://github.com/owner/repo/issues/123

更新 Agent 任务

更新现有 Agent 任务：

# Update description
gh agent-task update 123 "Updated task description"

# Update from file
gh agent-task update 123 --from-file updated-description.md

任务描述格式

Agent 任务描述应使用清晰、具体的自然语言指令：

优秀示例：

# Refactor User Authentication

Refactor the user authentication flow in `src/auth/login.js` to:
1. Use async/await instead of callbacks
2. Add proper error handling with specific error messages
3. Add input validation for email format
4. Update tests to cover the new implementation

Maintain backward compatibility with the existing API.

较差示例：

Fix auth

最佳实践：

• 明确说明需要更改的内容
• 适当时引用文件路径
• 包含验收标准
• 指明任何约束或要求
• 说明测试预期

与 GitHub Agentic Workflows 集成

GitHub Agentic Workflows（gh-aw）中的 create-agent-task 安全输出功能会使用 gh agent-task 扩展。

安全输出配置

safe-outputs:
  create-agent-task:
    base: main                       # Base branch for agent task PR
    target-repo: "owner/target-repo" # Cross-repository task creation

工作流示例

on:
  issues:
    types: [labeled]
permissions:
  contents: read
  actions: read
engine: claude
safe-outputs:
  create-agent-task:
    base: main

# Code Task Delegator

When an issue is labeled with "code-task", analyze the requirements and create a GitHub Copilot coding agent task with detailed instructions for implementing the requested changes.

实现细节

安全输出处理器会：

1. 读取工作流执行时的 Agent 输出
2. 从结构化输出中提取 create_agent_task 项
3. 将任务描述写入临时文件
4. 执行 gh agent-task create --from-file <file> --base <branch>
5. 获取已创建任务的 URL 和编号
6. 在作业摘要中报告结果

环境变量：

• GITHUB_AW_AGENT_TASK_BASE：拉取请求的基分支
• GITHUB_AW_TARGET_REPO：跨仓库创建任务时的目标仓库
• GITHUB_AW_SAFE_OUTPUTS_STAGED：预览模式标志

身份验证要求

创建 Agent 任务所需的权限高于默认 GITHUB_TOKEN 所提供的权限：

所需权限：

• contents: write - 用于创建分支和提交
• issues: write - 用于创建 Agent 任务 issue
• pull-requests: write - 用于创建拉取请求

令牌优先级：

1. COPILOT_GITHUB_TOKEN - 专用于 Copilot 操作的令牌（推荐）
2. GH_AW_GITHUB_TOKEN - 通用覆盖令牌（旧版）
3. 通过 github-token 配置字段指定的自定义令牌

注意：不支持默认的 GITHUB_TOKEN，因为它缺少所需权限。从 v0.26+ 起，不再支持 COPILOT_CLI_TOKEN 和 GH_AW_COPILOT_TOKEN 密钥。

设置身份验证

将个人访问令牌存储在仓库密钥中：

# In your repository settings, add secret:
# Name: COPILOT_GITHUB_TOKEN (recommended)
# Value: ghp_YourPersonalAccessToken

:::note[向后兼容性] 旧版令牌名称 GH_AW_GITHUB_TOKEN 仍受支持，以保证向后兼容。从 v0.26+ 起，不再支持 GH_AW_COPILOT_TOKEN 令牌。 :::

错误处理

身份验证错误

Error: failed to create agent task
authentication required

解决方案：配置 COPILOT_GITHUB_TOKEN 或旧版 GH_AW_GITHUB_TOKEN，并提供 PAT。

权限错误

Error: 403 Forbidden
Resource not accessible by integration

解决方案：确保令牌具有 contents: write、issues: write 和 pull-requests: write 权限。

未找到存储库

Error: repository not found

解决方案：确认目标存储库存在，并且令牌有权访问它。

在暂存模式下测试

当 safe-outputs.staged: true 时，Agent 任务会在创建前预览：

safe-outputs:
  staged: true
  create-agent-task:

暂存输出：

## 🎭 Staged Mode: Create Agent Tasks Preview

The following agent tasks would be created if staged mode was disabled:

### Task 1

**Description:**
Refactor authentication to use async/await pattern

**Base Branch:** main

**Target Repository:** owner/repo

常见模式

由 Issue 触发的 Agent 任务

on:
  issues:
    types: [labeled]
engine: claude
safe-outputs:
  create-agent-task:

When issue is labeled with "needs-implementation", create an agent task with implementation instructions.

定时代码改进

on:
  schedule:
    - cron: "0 9 * * 1"  # Monday 9AM
engine: copilot
safe-outputs:
  create-agent-task:
    base: develop

Analyze codebase for improvement opportunities and create agent tasks for top 3 improvements.

跨存储库任务委派

on: workflow_dispatch
engine: claude
safe-outputs:
  create-agent-task:
    target-repo: "organization/backend-repo"
    base: main

Create agent task in backend repository to implement the API changes described in this issue.

最佳实践

任务描述指南

1. 具体明确：包含文件路径、函数名称和确切要求
2. 提供上下文：说明为何需要此项更改
3. 明确成功标准：指定验收标准或预期结果
4. 提及测试：要求为更改编写测试
5. 设定约束：注明任何兼容性要求或限制

安全注意事项

1. 令牌安全：将 PAT 存储为机密，切勿提交到存储库
2. 权限范围：为令牌配置所需的最低权限
3. 存储库访问权限：在创建任务前验证目标存储库
4. 审查流程：为 Agent 生成的代码建立审查工作流

操作指南

1. 监控使用情况：跟踪 Agent 任务的创建和完成率
2. 审查输出：始终审查 Agent 生成的拉取请求
3. 迭代改进：根据 Agent 的表现优化任务描述
4. 记录文档：为常见任务类型维护模式

故障排查

任务创建静默失败

症状：没有错误，但也没有创建任务

检查：

1. 确认已在存储库机密中设置 COPILOT_GITHUB_TOKEN
2. 确认令牌具有所需权限
3. 检查作业日志中的错误消息
4. 确认目标存储库存在且可访问

Agent 任务未触发 Copilot

症状：已创建任务，但没有自动 PR

可能原因：

1. 存储库未启用 GitHub Copilot
2. 任务描述不清晰或含糊不清
3. 存储库设置阻止了自动 PR
4. Copilot 服务出现问题

解决方案：检查存储库的 Copilot 设置并优化任务描述。

跨存储库任务失败

症状：在不同存储库中创建任务时出错

检查：

1. 令牌有权访问目标存储库
2. 目标存储库存在且名称拼写正确
3. 令牌在目标存储库中具有所需权限

输出结构

通过 safe outputs 使用时，create-agent-task 作业会提供以下输出：

outputs:
  task_number: "123"
  task_url: "https://github.com/owner/repo/issues/123"

在依赖作业中使用：

jobs:
  follow_up:
    needs: create_agent_task
    steps:
      - name: Notify team
        run: |
          echo "Agent task created: ${{ needs.create_agent_task.outputs.task_url }}"

参考资料

• GitHub Copilot 文档
• GitHub CLI 扩展
• Safe Outputs 文档
• 个人访问令牌