`assign-to-agent` fails with GitHub App tokens — Copilot assignment API requires a PAT

[mason-tim]

assign-to-agent fails with GitHub App tokens — Copilot assignment API requires a PAT

Summary

When using github-app: authentication in safe-outputs with assign-to-agent, the Copilot assignment fails with:

copilot coding agent (copilot-swe-agent) is not available as an assignee for this repository

The same repository works fine when assigning Copilot via the GitHub UI or using a fine-grained PAT with the same permissions. The root cause is that the GitHub Copilot assignment API does not accept GitHub App installation tokens — it specifically requires a PAT.

Analysis

Root Cause

The assign-to-agent safe output uses the token minted by create-github-app-token when github-app: is configured in safe-outputs. The Copilot assignment API (/repos/{owner}/{repo}/issues/{issue_number}/assignees with copilot-swe-agent) rejects GitHub App installation tokens regardless of the permissions granted.

This was confirmed by:

1. ✅ Assigning Copilot to issues manually via the GitHub UI — works
2. ✅ Using a fine-grained PAT with actions:write, contents:write, issues:write, pull-requests:write — works
3. ❌ Using a GitHub App installation token with the same permissions — fails with "not available as an assignee"
4. ❌ Adding permission-actions: write and permission-contents: write to the create-github-app-token step — still fails (rules out missing permissions on the App token)

Affected Files

• pkg/workflow/assign_to_agent.go — AssignToAgentConfig struct and parsing logic
• actions/setup/js/assign_to_agent.cjs — Runtime script that calls the GitHub API to assign the agent
• pkg/workflow/compiler_types.go — SafeOutputsConfig has both GitHubApp and GitHubToken fields
• docs/src/content/docs/reference/assign-to-copilot.mdx — Documentation

Secondary Issue: Missing Permissions in Compiled Output

When assign-to-agent is configured with github-app:, the compiler generates a create-github-app-token step requesting:

• permission-contents: read (should be write)
• permission-issues: write ✅
• permission-pull-requests: write ✅
• permission-actions: write missing entirely

The assign-to-copilot docs state the required permissions are: actions: write, contents: write, issues: write, pull-requests: write.

Reproduction

Workflow frontmatter (.md file)

safe-outputs:
  github-app:
    app-id: ${{ vars.APP_ID }}
    private-key: ${{ secrets.APP_PRIVATE_KEY }}
  assign-to-agent:
    max: 3
    target: "*"
    allowed: [copilot]

Steps to reproduce

1. Create a workflow .md with the above safe-outputs config using github-app: auth
2. Compile with gh aw compile (tested with v0.53.4)
3. Create an issue that triggers the workflow
4. Observe the assign_to_agent step in the safe_outputs job logs:

   copilot coding agent (copilot-swe-agent) is not available as an assignee for this repository
   

Environment

• gh-aw version: v0.53.4
• GitHub App permissions: Actions (R/W), Contents (R/W), Issues (R/W), Pull requests (R/W)
• Repository: Organization-owned, Copilot coding agent enabled and assignable via UI
• Failed runs: https://github.com/DigitalInnovation/agentic-workflows-poc-/actions/runs/22734628337

Implementation Plan

Option A: Auto-fallback to GH_AW_AGENT_TOKEN (Recommended)

When assign-to-agent is configured and github-app: is the auth method, the compiler should automatically use the GH_AW_AGENT_TOKEN secret for the assignment step instead of the App installation token. The magic secret is already documented but the compiler doesn't wire it up when github-app: is present.

1. Update compiler (pkg/workflow/safe_outputs.go or equivalent):

   • When emitting the assign_to_agent step in the safe_outputs job, check if github-app: is the configured auth and no explicit github-token: is set
   • In that case, use ${{ secrets.GH_AW_AGENT_TOKEN }} as the github-token for the assignment step
   • Keep using the App token for all other safe outputs (add-comment, create-issue, etc.) which work fine with App tokens

2. Add validation/warning (pkg/workflow/validation.go or equivalent):

   • When assign-to-agent is configured with github-app: and no github-token: override, emit a compiler warning:

     "assign-to-agent requires a fine-grained PAT. Set the GH_AW_AGENT_TOKEN secret or add github-token: to your assign-to-agent config. GitHub App tokens are not supported for Copilot assignment."
     

3. Update tests (pkg/workflow/safe_outputs_test.go, actions/setup/js/assign_to_agent.test.cjs):

   • Test that assign-to-agent with github-app: auth falls back to GH_AW_AGENT_TOKEN
   • Test that explicit github-token: on assign-to-agent overrides both App token and magic secret
   • Test that the compiler warning is emitted

Option B: Fix permissions (even if Option A is implemented)

4. Fix token permissions (pkg/workflow/safe_outputs.go or equivalent):

   • When assign-to-agent is configured, the create-github-app-token step should request:
     • permission-actions: write (currently missing)
     • permission-contents: write (currently read)
   • This is needed even if Option A is implemented, for cases where a future GitHub API update enables App token support

5. Update documentation (docs/src/content/docs/reference/assign-to-copilot.mdx):

   • The "Using a GitHub App" section currently says: "Alternatively, you can use a GitHub App with appropriate permissions instead of a PAT for enhanced security."
   • This should be updated to clarify that GitHub App tokens do not currently work for the Copilot assignment API
   • Add a note that GH_AW_AGENT_TOKEN (PAT) is required even when using github-app: for other safe outputs

Follow Guidelines

• Use error message format: "[what's wrong]. [what's expected]. [example]"
• Run make agent-finish before completing