npx skills add ...
npx skills add github/gh-aw --skill gh-agent-session
npx skills add github/gh-aw --skill gh-agent-session
Use gh agent-session commands to inspect and manage agent sessions.
The gh agent-task extension creates GitHub Copilot coding agent sessions from the CLI. A session is a GitHub issue that triggers automated code changes from natural language instructions.
Repository: https://github.com/github/agent-task (internal GitHub extension)
Agent sessions are GitHub issues that:
Install via GitHub CLI:
Note: This extension requires authentication with a Personal Access Token (PAT) that has appropriate permissions for creating issues and pull requests.
Create a new agent session from a description:
Command Parameters:
--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:
List agent sessions in a repository:
View details of a specific agent session:
Update an existing agent session:
Agent session descriptions should be clear, specific natural language instructions:
Good Example:
Poor Example:
Best Practices:
The gh agent-task extension is used by the create-agent-session safe output feature in GitHub Agentic Workflows (gh-aw).
The safe output processor:
create_agent_task items from the structured outputgh agent-task create --from-file <file> --base <branch>Environment Variables:
GITHUB_AW_AGENT_TASK_BASE: Base branch for the pull requestGITHUB_AW_TARGET_REPO: Target repository for cross-repo task creationGITHUB_AW_SAFE_OUTPUTS_STAGED: Preview mode flagAgent session creation requires elevated permissions beyond the default GITHUB_TOKEN:
Required Permissions:
contents: write - To create branches and commitsissues: write - To create the agent session issuepull-requests: write - To create pull requestsToken Precedence:
COPILOT_GITHUB_TOKEN - Dedicated Copilot operations token (recommended)GH_AW_GITHUB_TOKEN - General override token (legacy)github-token configuration fieldNote: 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+.
Store your Personal Access Token in repository secrets:
:::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+.
:::
Solution: Configure COPILOT_GITHUB_TOKEN or legacy GH_AW_GITHUB_TOKEN with a PAT.
Solution: Ensure the token has contents: write, issues: write, and pull-requests: write permissions.
Solution: Verify the target repository exists and the token has access to it.
When safe-outputs.staged: true, agent sessions are previewed without creation:
Staged Output:
Symptom: No error but no task created
Check:
COPILOT_GITHUB_TOKEN is set in repository secretsSymptom: Task created but no automated PR
Possible Causes:
Solution: Check repository Copilot settings and refine task description.
Symptom: Error when creating tasks in different repository
Check:
When used via safe outputs, the create-agent-session job provides outputs:
Usage in Dependent Jobs:
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 authsafe-outputs:
create-agent-session:
base: main # Base branch for agent session PR
target-repo: "owner/target-repo" # Cross-repository task creationon:
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.# In your repository settings, add secret:
# Name: COPILOT_GITHUB_TOKEN (recommended)
# Value: ghp_YourPersonalAccessTokenError: failed to create agent session
authentication requiredError: 403 Forbidden
Resource not accessible by integrationError: repository not foundsafe-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/repoon:
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.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 }}"