gh-agent-session

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 sessions
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-session 安全输出功能会使用 gh agent-task 扩展。

安全输出配置

safe-outputs:
  create-agent-session:
    base: main                       # Base branch for agent session 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-session:
    base: main

# Code Task Delegator

When an issue is labeled with "code-task", analyze the requirements and create a GitHub Copilot coding agent session 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 session
authentication required

解决方案：使用 PAT 配置 COPILOT_GITHUB_TOKEN 或旧版 GH_AW_GITHUB_TOKEN。

权限错误

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-session:

暂存输出：

## 🎭 Staged Mode: Create Agent Tasks Preview

The following agent sessions 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

常见模式

由议题触发的 Agent 任务

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

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

定期进行代码改进

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

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

跨仓库任务委派

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

Create agent session 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. 令牌在目标仓库中具有所需权限

输出结构

通过安全输出使用时，create-agent-session 作业会提供以下输出：

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 session created: ${{ needs.create_agent_task.outputs.task_url }}"

参考资料

• GitHub Copilot 文档
• GitHub CLI 扩展
• 安全输出文档
• 个人访问令牌