gh-agent-task

GitHub CLI Agent Task 拡張機能

gh agent-task 拡張機能を使用すると、CLI から GitHub Copilot コーディングエージェントのタスクを作成できます。タスクとは、自然言語の指示に基づいて自動的にコードを変更する GitHub イシューです。

リポジトリ: https://github.com/github/agent-task（GitHub 内部向け拡張機能）

概要

エージェントタスクは、次のような GitHub イシューです。

• コード変更の自然言語による指示を含みます
• GitHub Copilot を起動して、タスクを自律的に実行します
• 実装した変更を含むプルリクエストを作成します
• 自動化されたコード変更をレビューしてマージするためのワークフローを提供します

インストール

GitHub CLI からインストールします。

gh extension install github/agent-task

注：この拡張機能を使用するには、イシューとプルリクエストの作成に必要な権限を持つ Personal Access Token（PAT）で認証する必要があります。

主なコマンド

エージェントタスクの作成

説明を指定して新しいエージェントタスクを作成します。

# 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>：対象リポジトリ（デフォルト：現在のリポジトリ）

出力形式： コマンドは作成したエージェントタスクの URL を出力します。

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

エージェントタスクの一覧表示

リポジトリ内のエージェントタスクを一覧表示します。

# 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

エージェントタスクの表示

特定のエージェントタスクの詳細を表示します。

# View by number
gh agent-task view 123

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

エージェントタスクの更新

既存のエージェントタスクを更新します。

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

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

タスクの説明形式

エージェントタスクの説明には、明確で具体的な自然言語の指示を記述してください。

良い例：

# 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 との連携

gh agent-task 拡張機能は、GitHub Agentic Workflows（gh-aw）の create-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. ワークフローの実行結果からエージェントの出力を読み込みます
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：プレビューモードのフラグ

認証要件

エージェントタスクの作成には、デフォルトの GITHUB_TOKEN よりも高い権限が必要です。

必要な権限：

• contents: write - ブランチとコミットを作成するため
• issues: write - エージェントタスクのイシューを作成するため
• pull-requests: write - プルリクエストを作成するため

トークンの優先順位：

1. COPILOT_GITHUB_TOKEN - Copilot 操作専用のトークン（推奨）
2. GH_AW_GITHUB_TOKEN - 汎用の上書きトークン（レガシー）
3. github-token 設定フィールドで指定するカスタムトークン

注：デフォルトの GITHUB_TOKEN は必要な権限がないため、サポートされていません。COPILOT_CLI_TOKEN と GH_AW_COPILOT_TOKEN のシークレットは、v0.26 以降サポートされていません。

認証の設定

Personal Access Token をリポジトリのシークレットに保存します。

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

:::note[後方互換性] レガシーのトークン名 GH_AW_GITHUB_TOKEN は、後方互換性のため引き続きサポートされています。GH_AW_COPILOT_TOKEN トークンは、v0.26 以降サポートされていません。 :::

エラー処理

認証エラー

Error: failed to create agent task
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 の場合、エージェントタスクは作成されずにプレビューされます。

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 をトリガーとするエージェントタスク

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. レビューのプロセス：エージェントが生成したコードのレビュー用ワークフローを確立します

運用ガイドライン

1. 使用状況を監視する：エージェントタスクの作成数と完了率を追跡します
2. 出力をレビューする：エージェントが生成したプルリクエストは必ずレビューしてください
3. 反復して改善する：エージェントのパフォーマンスに基づいてタスクの説明を改善します
4. 文書化する：よくあるタスクの種類に関するパターンを管理します

トラブルシューティング

タスクの作成が失敗しても何も表示されない

症状：エラーは表示されないものの、タスクが作成されない

確認事項：

1. リポジトリのシークレットに COPILOT_GITHUB_TOKEN が設定されていることを確認します
2. トークンに必要な権限があることを確認します
3. ジョブのログにエラーメッセージがないか確認します
4. 対象のリポジトリが存在し、アクセス可能であることを確認します

エージェントタスクによって Copilot が起動しない

症状：タスクは作成されたものの、自動的な PR が作成されない

考えられる原因：

1. リポジトリで GitHub Copilot が有効になっていない
2. タスクの説明が不明瞭、または曖昧
3. リポジトリの設定で自動 PR がブロックされている
4. Copilot サービスに問題がある

解決策：リポジトリの Copilot 設定を確認し、タスクの説明を改善してください。

リポジトリをまたぐタスクが失敗する

症状：別のリポジトリでタスクを作成するとエラーが発生する

確認事項：

1. トークンが対象のリポジトリにアクセスできること
2. 対象のリポジトリが存在し、名前に誤りがないこと
3. トークンに対象のリポジトリで必要な権限があること

出力構造

セーフアウトプット経由で使用する場合、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 拡張機能
• セーフアウトプットのドキュメント
• Personal Access Token