GitHub CLI Agent Session Extension

The gh agent-task CLI extension enables creating GitHub Copilot agent sessions through the command line. An agent session is a specialized GitHub issue that triggers GitHub Copilot to perform automated code changes based on natural language instructions.

Repository: https://github.com/github/agent-task (internal GitHub extension)

Overview

Agent sessions are GitHub issues that:

• Contain natural language instructions for code changes
• Trigger GitHub Copilot to autonomously execute the task
• Create pull requests with the implemented changes
• Provide a workflow for reviewing and merging automated code modifications

Installation

Install via GitHub CLI:

bash
1gh extension install github/agent-task

Note: This extension requires authentication with a Personal Access Token (PAT) that has appropriate permissions for creating issues and pull requests.

Core Commands

Create Agent Task

Create a new agent session from a description:

bash
1# Create task with inline description
2gh agent-task create "Fix the bug in authentication flow"
3
4# Create task from file
5gh agent-task create --from-file task-description.md
6
7# Specify base branch
8gh agent-task create --base develop "Implement new feature"
9
10# Create in different repository
11gh agent-task create --repo owner/repo "Update documentation"

Command Parameters:

• Description (positional): Natural language description of the task
• --from-file <path>: Read task description from file
• --base <branch>: Base branch for the pull request (default: repository default branch)
• --repo <owner/repo>: Target repository (default: current repository)

Output Format: The command outputs the URL of the created agent session:

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

List Agent Tasks

List agent sessions in a repository:

bash
1# List all agent sessions
2gh agent-task list
3
4# List with filters
5gh agent-task list --state open
6gh agent-task list --state closed
7gh agent-task list --state all

View Agent Task

View details of a specific agent session:

bash
1# View by number
2gh agent-task view 123
3
4# View by URL
5gh agent-task view https://github.com/owner/repo/issues/123

Update Agent Task

Update an existing agent session:

bash
1# Update description
2gh agent-task update 123 "Updated task description"
3
4# Update from file
5gh agent-task update 123 --from-file updated-description.md

Task Description Format

Agent session descriptions should be clear, specific natural language instructions:

Good Example:

markdown
1# Refactor User Authentication
2
3Refactor the user authentication flow in `src/auth/login.js` to:
41. Use async/await instead of callbacks
52. Add proper error handling with specific error messages
63. Add input validation for email format
74. Update tests to cover the new implementation
8
9Maintain backward compatibility with the existing API.

Poor Example:

markdown
1Fix auth

Best Practices:

• Be specific about what needs to change
• Reference file paths when relevant
• Include acceptance criteria
• Specify any constraints or requirements
• Mention testing expectations

Integration with GitHub Agentic Workflows

The gh agent-task extension is used by the create-agent-session safe output feature in GitHub Agentic Workflows (gh-aw).

Safe Output Configuration

yaml
1safe-outputs:
2  create-agent-session:
3    base: main                       # Base branch for agent session PR
4    target-repo: "owner/target-repo" # Cross-repository task creation

Workflow Example

yaml
1on:
2  issues:
3    types: [labeled]
4permissions:
5  contents: read
6  actions: read
7engine: claude
8safe-outputs:
9  create-agent-session:
10    base: main
11
12# Code Task Delegator
13
14When an issue is labeled with "code-task", analyze the requirements and create a GitHub Copilot agent session with detailed instructions for implementing the requested changes.

Implementation Details

The safe output processor:

1. Reads agent output from the workflow execution
2. Extracts create_agent_task items from the structured output
3. Writes task descriptions to temporary files
4. Executes gh agent-task create --from-file <file> --base <branch>
5. Captures the created task URL and number
6. Reports results in job summary

Environment Variables:

• GITHUB_AW_AGENT_TASK_BASE: Base branch for the pull request
• GITHUB_AW_TARGET_REPO: Target repository for cross-repo task creation
• GITHUB_AW_SAFE_OUTPUTS_STAGED: Preview mode flag

Authentication Requirements

Agent session creation requires elevated permissions beyond the default GITHUB_TOKEN:

Required Permissions:

• contents: write - To create branches and commits
• issues: write - To create the agent session issue
• pull-requests: write - To create pull requests

Token Precedence:

1. COPILOT_GITHUB_TOKEN - Dedicated Copilot operations token (recommended)
2. GH_AW_GITHUB_TOKEN - General override token (legacy)
3. Custom token via github-token configuration field

Note: The default GITHUB_TOKEN is not supported as it lacks required permissions. The COPILOT_CLI_TOKEN and GH_AW_COPILOT_TOKEN secrets are no longer supported as of v0.26+.

Setting Up Authentication

Store your Personal Access Token in repository secrets:

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

:::note[Backward Compatibility] Legacy token name GH_AW_GITHUB_TOKEN is still supported for backward compatibility. The GH_AW_COPILOT_TOKEN token is no longer supported as of v0.26+. :::

Error Handling

Authentication Errors

Error: failed to create agent session
authentication required

Solution: Configure COPILOT_GITHUB_TOKEN or legacy GH_AW_GITHUB_TOKEN with a PAT.

Permission Errors

Error: 403 Forbidden
Resource not accessible by integration

Solution: Ensure the token has contents: write, issues: write, and pull-requests: write permissions.

Repository Not Found

Error: repository not found

Solution: Verify the target repository exists and the token has access to it.

Testing in Staged Mode

When safe-outputs.staged: true, agent sessions are previewed without creation:

yaml
1safe-outputs:
2  staged: true
3  create-agent-session:

Staged Output:

markdown
1## 🎭 Staged Mode: Create Agent Tasks Preview
2
3The following agent sessions would be created if staged mode was disabled:
4
5### Task 1
6
7**Description:**
8Refactor authentication to use async/await pattern
9
10**Base Branch:** main
11
12**Target Repository:** owner/repo

Common Patterns

Issue-Triggered Agent Tasks

yaml
1on:
2  issues:
3    types: [labeled]
4engine: claude
5safe-outputs:
6  create-agent-session:
7
8When issue is labeled with "needs-implementation", create an agent session with implementation instructions.

Scheduled Code Improvements

yaml
1on:
2  schedule:
3    - cron: "0 9 * * 1"  # Monday 9AM
4engine: copilot
5safe-outputs:
6  create-agent-session:
7    base: develop
8
9Analyze codebase for improvement opportunities and create agent sessions for top 3 improvements.

Cross-Repository Task Delegation

yaml
1on: workflow_dispatch
2engine: claude
3safe-outputs:
4  create-agent-session:
5    target-repo: "organization/backend-repo"
6    base: main
7
8Create agent session in backend repository to implement the API changes described in this issue.

Best Practices

Task Description Guidelines

1. Be Specific: Include file paths, function names, and exact requirements
2. Include Context: Explain why the change is needed
3. Define Success: Specify acceptance criteria or expected outcomes
4. Mention Tests: Request test coverage for changes
5. Set Constraints: Note any compatibility requirements or limitations

Security Considerations

1. Token Security: Store PATs as secrets, never commit to repository
2. Permission Scope: Use minimum required permissions on tokens
3. Repository Access: Validate target repository before task creation
4. Review Process: Establish review workflow for agent-generated code

Operational Guidelines

1. Monitor Usage: Track agent session creation and completion rates
2. Review Output: Always review agent-generated pull requests
3. Iterate: Refine task descriptions based on agent performance
4. Document: Maintain patterns for common task types

Troubleshooting

Task Creation Fails Silently

Symptom: No error but no task created

Check:

1. Verify COPILOT_GITHUB_TOKEN is set in repository secrets
2. Confirm token has required permissions
3. Check job logs for error messages
4. Verify target repository exists and is accessible

Agent Task Not Triggering Copilot

Symptom: Task created but no automated PR

Possible Causes:

1. GitHub Copilot not enabled for repository
2. Task description unclear or ambiguous
3. Repository settings blocking automated PRs
4. Copilot service issues

Solution: Check repository Copilot settings and refine task description.

Cross-Repository Tasks Fail

Symptom: Error when creating tasks in different repository

Check:

1. Token has access to target repository
2. Target repository exists and is spelled correctly
3. Token has required permissions in target repository

Output Structure

When used via safe outputs, the create-agent-session job provides outputs:

yaml
1outputs:
2  task_number: "123"
3  task_url: "https://github.com/owner/repo/issues/123"

Usage in Dependent Jobs:

yaml
1jobs:
2  follow_up:
3    needs: create_agent_task
4    steps:
5      - name: Notify team
6        run: |
7          echo "Agent session created: ${{ needs.create_agent_task.outputs.task_url }}"

References

• GitHub Copilot Documentation
• GitHub CLI Extensions
• Safe Outputs Documentation
• Personal Access Tokens