gh-agent-session

GitHub CLI Agent Session 拡張機能

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

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

特定のエージェントセッションの詳細を表示します。

# 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-session セーフ出力機能で使用されます。

セーフ出力の設定

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. ワークフローの実行からエージェントの出力を読み取ります
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 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 の場合、エージェントセッションは作成されず、プレビューされます。

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

よくあるパターン

Issue をトリガーとするエージェントタスク

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

運用ガイドライン

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. 対象のリポジトリでトークンに必要な権限がある

出力構造

safe outputs 経由で使用すると、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 拡張機能
• Safe Outputs のドキュメント
• Personal Access Tokens