Clarify Copilot agent assignment methods in documentation

[Copilot]

Documentation used ambiguous @copilot syntax without distinguishing between two distinct assignment mechanisms. After code review, corrected critical documentation errors about token usage and GraphQL implementation.

Changes

Terminology corrections

• Replaced @copilot GitHub mention syntax with accurate method references in researchplanassign.md and blog post
• Updated to "assigned to Copilot" to match official GitHub documentation terminology

Cross-references to official GitHub documentation

• Added hyperlinks to official GitHub Copilot documentation throughout guides and reference docs
• tokens.md: Enhanced with links to official Copilot coding agent docs
• safe-outputs.md: Added notes that both methods mirror standard GitHub UI assignment workflow
• All terminology now aligns with official GitHub documentation

Corrected token and GraphQL implementation documentation

• Critical correction: Both methods use GH_AW_AGENT_TOKEN (NOT different tokens as previously documented)
• Documented that both methods use GraphQL replaceActorsForAssignable mutation via assign_agent_helpers.cjs
• Clarified that assignees: copilot in create-issue filters copilot and assigns it in a separate GraphQL step
• Added technical implementation details about token precedence chain
• Updated tokens.md and safe-outputs.md with accurate token information

Two Assignment Methods (Corrected)

Both methods use the same token (GH_AW_AGENT_TOKEN) and same GraphQL API:

Method 1: create-issue: assignees: copilot

safe-outputs:
  create-issue:
    assignees: copilot  # Copilot filtered and assigned via GraphQL

• Copilot is automatically filtered from assignees list
• Issue created with non-copilot assignees only
• Separate post-step assigns copilot via GraphQL using GH_AW_AGENT_TOKEN

Method 2: assign-to-agent: safe output

safe-outputs:
  assign-to-agent:
    name: "copilot"  # Direct GraphQL assignment to existing issue/PR

• For programmatic assignment to existing issues or PRs
• Direct GraphQL call with same token and mutation

Token precedence for both: GH_AW_AGENT_TOKEN || GH_AW_GITHUB_TOKEN || GITHUB_TOKEN

Both methods use the same underlying implementation (replaceActorsForAssignable GraphQL mutation) and result in the same outcome as manually assigning issues to Copilot through the GitHub UI.

[!WARNING]

Custom agent used: technical-doc-writer
AI technical documentation writer for GitHub Actions library using GitHub Docs voice

Original prompt

Review docs mentioning "assign to copilot" and make sure they match the implementation of the code and https://githubnext.github.io/gh-aw/reference/tokens/#gh_aw_agent_token-agent-assignment

Custom agent used: technical-doc-writer
AI technical documentation writer for GitHub Actions library using GitHub Docs voice

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[pelikhan]

@copilot review official GitHub documentation as well. Cross reference

[pelikhan]

@copilot, review the implementation of create-issue and ensure that it still uses the same token. It appears to create Copilot specially and may use GraphQL.

[Copilot]

@copilot review official GitHub documentation as well. Cross reference

Cross-referenced with official GitHub documentation and updated all terminology to match. Changes in commit 6507eae:

Official Docs Reviewed:

• Assigning issues to Copilot
• About Copilot coding agent

Key Updates:

1. Changed terminology from "assign to GitHub Copilot agent" → "assigned to Copilot" (matching official docs)
2. Added hyperlinks to official GitHub documentation throughout guides and reference docs
3. Enhanced tokens.md and safe-outputs.md with links to official Copilot docs
4. Clarified that both workflow methods mirror the standard GitHub UI assignment flow

All documentation now uses consistent terminology with official GitHub docs while explaining both the UI workflow (manual assignment) and the programmatic workflow methods (assignees: copilot and assign-to-agent safe output).

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• telemetry.astro.build
  • Triggering command: /opt/hostedtoolcache/node/24.12.0/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro build (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[Copilot]

@copilot, review the implementation of create-issue and ensure that it still uses the same token. It appears to create Copilot specially and may use GraphQL.

Reviewed the implementation and corrected the documentation. Key findings in commit eb3ebdb:

Both methods use the SAME token and GraphQL API:

1. create-issue: assignees: copilot:

   • Token: GH_AW_AGENT_TOKEN (NOT COPILOT_GITHUB_TOKEN as previously documented)
   • Implementation: Copilot is filtered from assignees list (see hasCopilotAssignee() in create_issue.go)
   • Separate post-step assigns copilot via GraphQL using assign_copilot_to_created_issues.cjs
   • Uses replaceActorsForAssignable GraphQL mutation via assign_agent_helpers.cjs

2. assign-to-agent safe output:

   • Token: GH_AW_AGENT_TOKEN (same as method 1)
   • Direct GraphQL call with same mutation

Token precedence for both: GH_AW_AGENT_TOKEN || GH_AW_GITHUB_TOKEN || GITHUB_TOKEN

Documentation now accurately reflects that both methods use identical token chain and GraphQL implementation.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• telemetry.astro.build
  • Triggering command: /opt/hostedtoolcache/node/24.12.0/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro build (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)