From da23774eaec2fa12d8fefbecd3a35bcafd625f84 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 22 Jan 2026 00:08:22 +0000 Subject: [PATCH 1/4] Initial plan From 025e77cc0226f15fca584c8381fcd5e657c5bdfa Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 22 Jan 2026 00:16:16 +0000 Subject: [PATCH 2/4] Fix "assign to copilot" documentation to match implementation Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- .../src/content/docs/agent-factory-status.mdx | 3 ++- .../blog/2026-01-27-operational-patterns.md | 2 +- .../content/docs/guides/researchplanassign.md | 12 ++++----- .../content/docs/reference/safe-outputs.md | 15 ++++++++++- docs/src/content/docs/reference/tokens.md | 26 +++++++++++++++++++ 5 files changed, 49 insertions(+), 9 deletions(-) diff --git a/docs/src/content/docs/agent-factory-status.mdx b/docs/src/content/docs/agent-factory-status.mdx index 7b73fd3321..26fe992a27 100644 --- a/docs/src/content/docs/agent-factory-status.mdx +++ b/docs/src/content/docs/agent-factory-status.mdx @@ -112,7 +112,6 @@ These are experimental agentic workflows used by the GitHub Next team to learn, | [Safe Output Health Monitor](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/safe-output-health.md) | claude | [![Safe Output Health Monitor](https://github.com/githubnext/gh-aw/actions/workflows/safe-output-health.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/safe-output-health.lock.yml) | - | - | | [Schema Consistency Checker](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/schema-consistency-checker.md) | claude | [![Schema Consistency Checker](https://github.com/githubnext/gh-aw/actions/workflows/schema-consistency-checker.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/schema-consistency-checker.lock.yml) | - | - | | [Scout](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/scout.md) | claude | [![Scout](https://github.com/githubnext/gh-aw/actions/workflows/scout.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/scout.lock.yml) | - | `/scout` | -| [Security Alert Burndown](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/security-alert-burndown.campaign.md) | copilot | [![Security Alert Burndown](https://github.com/githubnext/gh-aw/actions/workflows/security-alert-burndown.campaign.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/security-alert-burndown.campaign.lock.yml) | - | - | | [Security Compliance Campaign](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/security-compliance.md) | copilot | [![Security Compliance Campaign](https://github.com/githubnext/gh-aw/actions/workflows/security-compliance.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/security-compliance.lock.yml) | - | - | | [Security Fix PR](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/security-fix-pr.md) | copilot | [![Security Fix PR](https://github.com/githubnext/gh-aw/actions/workflows/security-fix-pr.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/security-fix-pr.lock.yml) | - | - | | [Security Review Agent πŸ”’](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/security-review.md) | copilot | [![Security Review Agent πŸ”’](https://github.com/githubnext/gh-aw/actions/workflows/security-review.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/security-review.lock.yml) | - | `/security` | @@ -122,12 +121,14 @@ These are experimental agentic workflows used by the GitHub Next team to learn, | [Smoke Claude](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/smoke-claude.md) | claude | [![Smoke Claude](https://github.com/githubnext/gh-aw/actions/workflows/smoke-claude.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/smoke-claude.lock.yml) | - | - | | [Smoke Codex](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/smoke-codex.md) | codex | [![Smoke Codex](https://github.com/githubnext/gh-aw/actions/workflows/smoke-codex.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/smoke-codex.lock.yml) | - | - | | [Smoke Copilot](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/smoke-copilot.md) | copilot | [![Smoke Copilot](https://github.com/githubnext/gh-aw/actions/workflows/smoke-copilot.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/smoke-copilot.lock.yml) | - | - | +| [Smoke OpenCode](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/smoke-opencode.md) | copilot | [![Smoke OpenCode](https://github.com/githubnext/gh-aw/actions/workflows/smoke-opencode.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/smoke-opencode.lock.yml) | - | - | | [Stale Repository Identifier](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/stale-repo-identifier.md) | copilot | [![Stale Repository Identifier](https://github.com/githubnext/gh-aw/actions/workflows/stale-repo-identifier.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/stale-repo-identifier.lock.yml) | - | - | | [Static Analysis Report](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/static-analysis-report.md) | claude | [![Static Analysis Report](https://github.com/githubnext/gh-aw/actions/workflows/static-analysis-report.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/static-analysis-report.lock.yml) | - | - | | [Step Name Alignment](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/step-name-alignment.md) | claude | [![Step Name Alignment](https://github.com/githubnext/gh-aw/actions/workflows/step-name-alignment.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/step-name-alignment.lock.yml) | `daily` | - | | [Sub-Issue Closer](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/sub-issue-closer.md) | copilot | [![Sub-Issue Closer](https://github.com/githubnext/gh-aw/actions/workflows/sub-issue-closer.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/sub-issue-closer.lock.yml) | - | - | | [Super Linter Report](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/super-linter.md) | copilot | [![Super Linter Report](https://github.com/githubnext/gh-aw/actions/workflows/super-linter.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/super-linter.lock.yml) | `0 14 * * 1-5` | - | | [Terminal Stylist](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/terminal-stylist.md) | copilot | [![Terminal Stylist](https://github.com/githubnext/gh-aw/actions/workflows/terminal-stylist.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/terminal-stylist.lock.yml) | - | - | +| [Test Create PR Error Handling](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/test-create-pr-error-handling.md) | claude | [![Test Create PR Error Handling](https://github.com/githubnext/gh-aw/actions/workflows/test-create-pr-error-handling.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/test-create-pr-error-handling.lock.yml) | - | - | | [The Daily Repository Chronicle](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/daily-repo-chronicle.md) | copilot | [![The Daily Repository Chronicle](https://github.com/githubnext/gh-aw/actions/workflows/daily-repo-chronicle.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/daily-repo-chronicle.lock.yml) | `0 16 * * 1-5` | - | | [The Great Escapi](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/firewall-escape.md) | copilot | [![The Great Escapi](https://github.com/githubnext/gh-aw/actions/workflows/firewall-escape.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/firewall-escape.lock.yml) | - | - | | [Tidy](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/tidy.md) | copilot | [![Tidy](https://github.com/githubnext/gh-aw/actions/workflows/tidy.lock.yml/badge.svg)](https://github.com/githubnext/gh-aw/actions/workflows/tidy.lock.yml) | `0 7 * * *` | - | diff --git a/docs/src/content/docs/blog/2026-01-27-operational-patterns.md b/docs/src/content/docs/blog/2026-01-27-operational-patterns.md index 24684efa4a..a42f6730b5 100644 --- a/docs/src/content/docs/blog/2026-01-27-operational-patterns.md +++ b/docs/src/content/docs/blog/2026-01-27-operational-patterns.md @@ -318,7 +318,7 @@ The [`duplicate-code-detector`](https://github.com/githubnext/gh-aw/tree/2c1f68a **Research**: Uses Serena MCP for semantic analysis, creates report **Plan**: Creates well-scoped issues (max 3 per run) with refactoring strategies -**Assign**: Pre-assigns to `@copilot` since fixes are straightforward +**Assign**: Creates issues with `assignees: copilot` since fixes are straightforward The key benefits are: diff --git a/docs/src/content/docs/guides/researchplanassign.md b/docs/src/content/docs/guides/researchplanassign.md index 040c541c6d..dfa35bbd8b 100644 --- a/docs/src/content/docs/guides/researchplanassign.md +++ b/docs/src/content/docs/guides/researchplanassign.md @@ -19,7 +19,7 @@ The developer reviews the research report to determine if worthwhile improvement ### Phase 3: Assign -The developer reviews the generated issues and decides which ones to execute. Approved issues are assigned to `@copilot` for automated implementation and can be executed sequentially or in parallel depending on dependencies. Each copilot agent creates a pull request with the implementation for developer review and merging. +The developer reviews the generated issues and decides which ones to execute. Approved issues are assigned to the GitHub Copilot agent for automated implementation and can be executed sequentially or in parallel depending on dependencies. Each agent creates a pull request with the implementation for developer review and merging. ## When to Use ResearchPlanAssign @@ -37,17 +37,17 @@ Runs daily to scan all agentic workflows with security tools (zizmor, poutine, a **Plan Phase**: Developer reviews the security discussion and uses the `/plan` command to convert high-priority findings into issues. -**Assign Phase**: Developer assigns generated issues to `@copilot` for automated fixes. +**Assign Phase**: Developer assigns generated issues to the GitHub Copilot agent for automated fixes. ### Duplicate Code Detection β†’ Plan β†’ Refactor **Research Phase**: [`duplicate-code-detector.md`](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/duplicate-code-detector.md) -Runs daily using Serena MCP for semantic code analysis to identify exact, structural, and functional duplication. Creates one issue per distinct pattern (max 3 per run) and assigns directly to `@copilot` since duplication fixes are typically straightforward. +Runs daily using Serena MCP for semantic code analysis to identify exact, structural, and functional duplication. Creates one issue per distinct pattern (max 3 per run) with `assignees: copilot` since duplication fixes are typically straightforward. **Plan Phase**: Since issues are already well-scoped, the plan phase is implicit in the research output. -**Assign Phase**: Issues are pre-assigned to `@copilot` for automated refactoring. +**Assign Phase**: Issues are created with `assignees: copilot` for automated refactoring. ### File Size Analysis β†’ Plan β†’ Refactor @@ -57,7 +57,7 @@ Runs weekdays to monitor file sizes, identify files exceeding healthy size thres **Plan Phase**: The research issue already contains a concrete refactoring plan. -**Assign Phase**: Developer reviews and assigns to `@copilot` or handles manually depending on complexity. +**Assign Phase**: Developer reviews and assigns to the GitHub Copilot agent or handles manually depending on complexity. ### Deep Research β†’ Plan β†’ Implementation @@ -79,7 +79,7 @@ Performs deep research investigations using multiple research MCPs (Tavily, arXi ## Customization -Adapt the ResearchPlanAssign strategy by customizing the research focus (static analysis, performance metrics, documentation quality, security, code duplication, test coverage), frequency (daily, weekly, on-demand), report format (discussions vs issues), planning approach (automatic vs manual), and assignment method (pre-assign to `@copilot`, manual, or mixed). +Adapt the ResearchPlanAssign strategy by customizing the research focus (static analysis, performance metrics, documentation quality, security, code duplication, test coverage), frequency (daily, weekly, on-demand), report format (discussions vs issues), planning approach (automatic vs manual), and assignment method (pre-assign with `assignees: copilot`, manual assignment, or mixed). ## Benefits diff --git a/docs/src/content/docs/reference/safe-outputs.md b/docs/src/content/docs/reference/safe-outputs.md index 6c6b9cf45e..b6b37872f8 100644 --- a/docs/src/content/docs/reference/safe-outputs.md +++ b/docs/src/content/docs/reference/safe-outputs.md @@ -779,7 +779,7 @@ Creates Copilot agent sessions. Requires `COPILOT_GITHUB_TOKEN` or `GH_AW_GITHUB ### Assign to Agent (`assign-to-agent:`) -Assigns Copilot coding agent to issues or pull requests. Requires fine-grained PAT with actions, contents, issues, pull requests write access stored as `GH_AW_AGENT_TOKEN`, or GitHub App token. Supported agents: `copilot` (`copilot-swe-agent`). +Assigns GitHub Copilot agents to **existing** issues or pull requests programmatically. Requires fine-grained PAT with actions, contents, issues, pull requests write access stored as `GH_AW_AGENT_TOKEN`, or GitHub App token. Supported agents: `copilot` (`copilot-swe-agent`). Auto-resolves target from workflow context (issue/PR events) when `issue_number` or `pull_number` not explicitly provided. Restrict with `allowed` list. Target: `"triggering"` (default), `"*"` (any), or number. @@ -801,6 +801,19 @@ safe-outputs: **Assignee Filtering:** When `allowed` list is configured, existing agent assignees not in the list are removed while regular user assignees are preserved. +> [!TIP] +> Assignment methods +> +> Use `assign-to-agent` when you need to assign agents to **existing** issues or PRs. If you're creating new issues and want to assign an agent immediately, use `assignees: copilot` in your [`create-issue`](#issue-creation-create-issue) configuration instead, which is simpler and uses `COPILOT_GITHUB_TOKEN`: +> +> ```yaml +> safe-outputs: +> create-issue: +> assignees: copilot # Assigns agent when creating issue +> ``` +> +> See [GitHub Tokens reference](/gh-aw/reference/tokens/#gh_aw_agent_token-agent-assignment) for token configuration details. + ### Assign to User (`assign-to-user:`) Assigns users to issues. Restrict with `allowed` list. Target: `"triggering"` (issue event), `"*"` (any), or number. Supports single or multiple assignees. diff --git a/docs/src/content/docs/reference/tokens.md b/docs/src/content/docs/reference/tokens.md index 7e4811a030..08e5db5a29 100644 --- a/docs/src/content/docs/reference/tokens.md +++ b/docs/src/content/docs/reference/tokens.md @@ -358,6 +358,32 @@ gh aw secrets set GH_AW_AGENT_TOKEN --value "YOUR_AGENT_PAT" **Token precedence**: per-output β†’ global safe-outputs β†’ workflow-level β†’ `GH_AW_AGENT_TOKEN` (no further fallback - must be explicitly configured) +> [!NOTE] +> Two ways to assign Copilot agents +> +> There are two different methods for assigning GitHub Copilot agents to issues or pull requests: +> +> 1. **Via `assign-to-agent` safe output** (uses `GH_AW_AGENT_TOKEN`): Use when you need to assign agents to **existing** issues or PRs after they've been created. This is a standalone operation that requires the token documented on this page. +> +> ```yaml +> safe-outputs: +> assign-to-agent: +> name: "copilot" +> allowed: [copilot] +> ``` +> +> 2. **Via `assignees` or `reviewers` fields** (uses `COPILOT_GITHUB_TOKEN`): Use when creating new issues or PRs and want to assign the agent immediately. This is configured as part of `create-issue` or `create-pull-request` safe outputs. +> +> ```yaml +> safe-outputs: +> create-issue: +> assignees: copilot # or assignees: [copilot, user1] +> create-pull-request: +> reviewers: copilot # or reviewers: [copilot, user1] +> ``` +> +> For most workflows that create issues with agent assignments, use method 2 (`assignees: copilot`) as it's simpler and uses the existing `COPILOT_GITHUB_TOKEN`. Use method 1 (`assign-to-agent`) when you need to assign agents to issues that already exist or when you need fine-grained control over agent assignment operations. + > [!NOTE] > Resource owner requirements > The token's resource owner must match the repository ownership: From 6507eaef6eb82432ef3d3825b0d5b49a4755f9d5 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 22 Jan 2026 00:24:51 +0000 Subject: [PATCH 3/4] Cross-reference official GitHub Copilot documentation Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- .../docs/blog/2026-01-27-operational-patterns.md | 2 +- docs/src/content/docs/guides/researchplanassign.md | 12 ++++++------ docs/src/content/docs/reference/safe-outputs.md | 6 +++--- docs/src/content/docs/reference/tokens.md | 10 ++++++---- 4 files changed, 16 insertions(+), 14 deletions(-) diff --git a/docs/src/content/docs/blog/2026-01-27-operational-patterns.md b/docs/src/content/docs/blog/2026-01-27-operational-patterns.md index a42f6730b5..966773b9cf 100644 --- a/docs/src/content/docs/blog/2026-01-27-operational-patterns.md +++ b/docs/src/content/docs/blog/2026-01-27-operational-patterns.md @@ -318,7 +318,7 @@ The [`duplicate-code-detector`](https://github.com/githubnext/gh-aw/tree/2c1f68a **Research**: Uses Serena MCP for semantic analysis, creates report **Plan**: Creates well-scoped issues (max 3 per run) with refactoring strategies -**Assign**: Creates issues with `assignees: copilot` since fixes are straightforward +**Assign**: Creates issues and [assigns to Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot) (via `assignees: copilot`) since fixes are straightforward The key benefits are: diff --git a/docs/src/content/docs/guides/researchplanassign.md b/docs/src/content/docs/guides/researchplanassign.md index dfa35bbd8b..3747f0fb7f 100644 --- a/docs/src/content/docs/guides/researchplanassign.md +++ b/docs/src/content/docs/guides/researchplanassign.md @@ -19,7 +19,7 @@ The developer reviews the research report to determine if worthwhile improvement ### Phase 3: Assign -The developer reviews the generated issues and decides which ones to execute. Approved issues are assigned to the GitHub Copilot agent for automated implementation and can be executed sequentially or in parallel depending on dependencies. Each agent creates a pull request with the implementation for developer review and merging. +The developer reviews the generated issues and decides which ones to execute. Approved issues are [assigned to Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot) for automated implementation and can be executed sequentially or in parallel depending on dependencies. Copilot creates a pull request with the implementation for developer review and merging. ## When to Use ResearchPlanAssign @@ -37,17 +37,17 @@ Runs daily to scan all agentic workflows with security tools (zizmor, poutine, a **Plan Phase**: Developer reviews the security discussion and uses the `/plan` command to convert high-priority findings into issues. -**Assign Phase**: Developer assigns generated issues to the GitHub Copilot agent for automated fixes. +**Assign Phase**: Developer [assigns generated issues to Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot) for automated fixes. ### Duplicate Code Detection β†’ Plan β†’ Refactor **Research Phase**: [`duplicate-code-detector.md`](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/duplicate-code-detector.md) -Runs daily using Serena MCP for semantic code analysis to identify exact, structural, and functional duplication. Creates one issue per distinct pattern (max 3 per run) with `assignees: copilot` since duplication fixes are typically straightforward. +Runs daily using Serena MCP for semantic code analysis to identify exact, structural, and functional duplication. Creates one issue per distinct pattern (max 3 per run) that are [assigned to Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot) (via `assignees: copilot` in workflow config) since duplication fixes are typically straightforward. **Plan Phase**: Since issues are already well-scoped, the plan phase is implicit in the research output. -**Assign Phase**: Issues are created with `assignees: copilot` for automated refactoring. +**Assign Phase**: Issues are created and [assigned to Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot) (via `assignees: copilot`) for automated refactoring. ### File Size Analysis β†’ Plan β†’ Refactor @@ -57,7 +57,7 @@ Runs weekdays to monitor file sizes, identify files exceeding healthy size thres **Plan Phase**: The research issue already contains a concrete refactoring plan. -**Assign Phase**: Developer reviews and assigns to the GitHub Copilot agent or handles manually depending on complexity. +**Assign Phase**: Developer reviews and [assigns to Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot) or handles manually depending on complexity. ### Deep Research β†’ Plan β†’ Implementation @@ -79,7 +79,7 @@ Performs deep research investigations using multiple research MCPs (Tavily, arXi ## Customization -Adapt the ResearchPlanAssign strategy by customizing the research focus (static analysis, performance metrics, documentation quality, security, code duplication, test coverage), frequency (daily, weekly, on-demand), report format (discussions vs issues), planning approach (automatic vs manual), and assignment method (pre-assign with `assignees: copilot`, manual assignment, or mixed). +Adapt the ResearchPlanAssign strategy by customizing the research focus (static analysis, performance metrics, documentation quality, security, code duplication, test coverage), frequency (daily, weekly, on-demand), report format (discussions vs issues), planning approach (automatic vs manual), and assignment method (pre-assign via `assignees: copilot` in workflow config, [manual assignment through GitHub UI](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot), or mixed). ## Benefits diff --git a/docs/src/content/docs/reference/safe-outputs.md b/docs/src/content/docs/reference/safe-outputs.md index b6b37872f8..16e9d90e24 100644 --- a/docs/src/content/docs/reference/safe-outputs.md +++ b/docs/src/content/docs/reference/safe-outputs.md @@ -779,7 +779,7 @@ Creates Copilot agent sessions. Requires `COPILOT_GITHUB_TOKEN` or `GH_AW_GITHUB ### Assign to Agent (`assign-to-agent:`) -Assigns GitHub Copilot agents to **existing** issues or pull requests programmatically. Requires fine-grained PAT with actions, contents, issues, pull requests write access stored as `GH_AW_AGENT_TOKEN`, or GitHub App token. Supported agents: `copilot` (`copilot-swe-agent`). +Programmatically assigns GitHub Copilot agents to **existing** issues or pull requests through workflow automation. This safe output automates the [standard GitHub workflow for assigning issues to Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot). Requires fine-grained PAT with actions, contents, issues, pull requests write access stored as `GH_AW_AGENT_TOKEN`, or GitHub App token. Supported agents: `copilot` (`copilot-swe-agent`). Auto-resolves target from workflow context (issue/PR events) when `issue_number` or `pull_number` not explicitly provided. Restrict with `allowed` list. Target: `"triggering"` (default), `"*"` (any), or number. @@ -804,7 +804,7 @@ When `allowed` list is configured, existing agent assignees not in the list are > [!TIP] > Assignment methods > -> Use `assign-to-agent` when you need to assign agents to **existing** issues or PRs. If you're creating new issues and want to assign an agent immediately, use `assignees: copilot` in your [`create-issue`](#issue-creation-create-issue) configuration instead, which is simpler and uses `COPILOT_GITHUB_TOKEN`: +> Use `assign-to-agent` when you need to programmatically assign agents to **existing** issues or PRs through workflow automation. If you're creating new issues and want to assign an agent immediately, use `assignees: copilot` in your [`create-issue`](#issue-creation-create-issue) configuration instead, which is simpler and uses `COPILOT_GITHUB_TOKEN`: > > ```yaml > safe-outputs: @@ -812,7 +812,7 @@ When `allowed` list is configured, existing agent assignees not in the list are > assignees: copilot # Assigns agent when creating issue > ``` > -> See [GitHub Tokens reference](/gh-aw/reference/tokens/#gh_aw_agent_token-agent-assignment) for token configuration details. +> Both methods result in the same outcome as [manually assigning issues to Copilot through the GitHub UI](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot), but are automated through workflow safe outputs. See [GitHub Tokens reference](/gh-aw/reference/tokens/#gh_aw_agent_token-agent-assignment) for token configuration details and [GitHub's official Copilot coding agent documentation](https://docs.github.com/en/copilot/concepts/agents/coding-agent/about-coding-agent) for more about the Copilot agent. ### Assign to User (`assign-to-user:`) diff --git a/docs/src/content/docs/reference/tokens.md b/docs/src/content/docs/reference/tokens.md index 08e5db5a29..7ceb511ef9 100644 --- a/docs/src/content/docs/reference/tokens.md +++ b/docs/src/content/docs/reference/tokens.md @@ -314,7 +314,7 @@ gh aw secrets set COPILOT_GITHUB_TOKEN --value "YOUR_COPILOT_PAT" **Type**: Personal Access Token (user must configure) -Specialized token for `assign-to-agent:` safe outputs that assign GitHub Copilot agents to issues or pull requests. +Specialized token for `assign-to-agent:` safe outputs that programmatically assign GitHub Copilot agents to issues or pull requests. This is distinct from the standard GitHub UI workflow for [assigning issues to Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot)β€”this token is used for automated agent assignment through workflow safe outputs. **Required for**: @@ -363,7 +363,7 @@ gh aw secrets set GH_AW_AGENT_TOKEN --value "YOUR_AGENT_PAT" > > There are two different methods for assigning GitHub Copilot agents to issues or pull requests: > -> 1. **Via `assign-to-agent` safe output** (uses `GH_AW_AGENT_TOKEN`): Use when you need to assign agents to **existing** issues or PRs after they've been created. This is a standalone operation that requires the token documented on this page. +> 1. **Via `assign-to-agent` safe output** (uses `GH_AW_AGENT_TOKEN`): Use when you need to programmatically assign agents to **existing** issues or PRs through workflow automation. This is a standalone operation that requires the token documented on this page. > > ```yaml > safe-outputs: @@ -372,7 +372,7 @@ gh aw secrets set GH_AW_AGENT_TOKEN --value "YOUR_AGENT_PAT" > allowed: [copilot] > ``` > -> 2. **Via `assignees` or `reviewers` fields** (uses `COPILOT_GITHUB_TOKEN`): Use when creating new issues or PRs and want to assign the agent immediately. This is configured as part of `create-issue` or `create-pull-request` safe outputs. +> 2. **Via `assignees` or `reviewers` fields** (uses `COPILOT_GITHUB_TOKEN`): Use when creating new issues or PRs through workflows and want to assign the agent immediately. This is configured as part of `create-issue` or `create-pull-request` safe outputs and mirrors the [standard GitHub UI flow for assigning issues to Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot). > > ```yaml > safe-outputs: @@ -382,7 +382,9 @@ gh aw secrets set GH_AW_AGENT_TOKEN --value "YOUR_AGENT_PAT" > reviewers: copilot # or reviewers: [copilot, user1] > ``` > -> For most workflows that create issues with agent assignments, use method 2 (`assignees: copilot`) as it's simpler and uses the existing `COPILOT_GITHUB_TOKEN`. Use method 1 (`assign-to-agent`) when you need to assign agents to issues that already exist or when you need fine-grained control over agent assignment operations. +> For most workflows that create issues with agent assignments, use method 2 (`assignees: copilot`) as it's simpler and uses the existing `COPILOT_GITHUB_TOKEN`. Use method 1 (`assign-to-agent`) when you need to programmatically assign agents to issues that already exist or when you need fine-grained control over agent assignment operations. +> +> See [GitHub's official documentation on assigning issues to Copilot](https://docs.github.com/en/copilot/concepts/agents/coding-agent/about-coding-agent) for more details on the Copilot coding agent. > [!NOTE] > Resource owner requirements From eb3ebdbb37addec10ca0365542a572491e3a8d4b Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 22 Jan 2026 00:34:18 +0000 Subject: [PATCH 4/4] Fix token documentation: Both methods use GH_AW_AGENT_TOKEN and GraphQL Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- docs/src/content/docs/reference/safe-outputs.md | 8 +++++--- docs/src/content/docs/reference/tokens.md | 12 ++++++------ 2 files changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/src/content/docs/reference/safe-outputs.md b/docs/src/content/docs/reference/safe-outputs.md index 16e9d90e24..2229981d5a 100644 --- a/docs/src/content/docs/reference/safe-outputs.md +++ b/docs/src/content/docs/reference/safe-outputs.md @@ -804,7 +804,7 @@ When `allowed` list is configured, existing agent assignees not in the list are > [!TIP] > Assignment methods > -> Use `assign-to-agent` when you need to programmatically assign agents to **existing** issues or PRs through workflow automation. If you're creating new issues and want to assign an agent immediately, use `assignees: copilot` in your [`create-issue`](#issue-creation-create-issue) configuration instead, which is simpler and uses `COPILOT_GITHUB_TOKEN`: +> Use `assign-to-agent` when you need to programmatically assign agents to **existing** issues or PRs through workflow automation. If you're creating new issues and want to assign an agent immediately, use `assignees: copilot` in your [`create-issue`](#issue-creation-create-issue) configuration instead, which is simpler: > > ```yaml > safe-outputs: @@ -812,7 +812,9 @@ When `allowed` list is configured, existing agent assignees not in the list are > assignees: copilot # Assigns agent when creating issue > ``` > -> Both methods result in the same outcome as [manually assigning issues to Copilot through the GitHub UI](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot), but are automated through workflow safe outputs. See [GitHub Tokens reference](/gh-aw/reference/tokens/#gh_aw_agent_token-agent-assignment) for token configuration details and [GitHub's official Copilot coding agent documentation](https://docs.github.com/en/copilot/concepts/agents/coding-agent/about-coding-agent) for more about the Copilot agent. +> **Important**: Both methods use the **same token** (`GH_AW_AGENT_TOKEN`) and **same GraphQL API** (`replaceActorsForAssignable` mutation) to assign copilot. When you use `assignees: copilot` in create-issue, the copilot assignee is automatically filtered out and assigned in a separate post-step using the agent token and GraphQL, identical to the `assign-to-agent` safe output. +> +> Both methods result in the same outcome as [manually assigning issues to Copilot through the GitHub UI](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot). See [GitHub Tokens reference](/gh-aw/reference/tokens/#gh_aw_agent_token-agent-assignment) for token configuration details and [GitHub's official Copilot coding agent documentation](https://docs.github.com/en/copilot/concepts/agents/coding-agent/about-coding-agent) for more about the Copilot agent. ### Assign to User (`assign-to-user:`) @@ -913,7 +915,7 @@ safe-outputs: ## Assigning to Copilot -Use `assignees: copilot` or `reviewers: copilot` for bot assignment. Requires `COPILOT_GITHUB_TOKEN` or `GH_AW_GITHUB_TOKEN` PATβ€”default `GITHUB_TOKEN` lacks permissions. +Use `assignees: copilot` or `reviewers: copilot` for bot assignment. Requires `GH_AW_AGENT_TOKEN` (or fallback to `GH_AW_GITHUB_TOKEN`/`GITHUB_TOKEN`)β€”uses GraphQL API to assign the bot. ## Custom Runner Image diff --git a/docs/src/content/docs/reference/tokens.md b/docs/src/content/docs/reference/tokens.md index 7ceb511ef9..24710e43ed 100644 --- a/docs/src/content/docs/reference/tokens.md +++ b/docs/src/content/docs/reference/tokens.md @@ -361,9 +361,9 @@ gh aw secrets set GH_AW_AGENT_TOKEN --value "YOUR_AGENT_PAT" > [!NOTE] > Two ways to assign Copilot agents > -> There are two different methods for assigning GitHub Copilot agents to issues or pull requests: +> There are two different methods for assigning GitHub Copilot agents to issues or pull requests. **Both methods use the same token (`GH_AW_AGENT_TOKEN`) and GraphQL API** to perform the assignment: > -> 1. **Via `assign-to-agent` safe output** (uses `GH_AW_AGENT_TOKEN`): Use when you need to programmatically assign agents to **existing** issues or PRs through workflow automation. This is a standalone operation that requires the token documented on this page. +> 1. **Via `assign-to-agent` safe output**: Use when you need to programmatically assign agents to **existing** issues or PRs through workflow automation. This is a standalone operation that requires the token documented on this page. > > ```yaml > safe-outputs: @@ -372,17 +372,17 @@ gh aw secrets set GH_AW_AGENT_TOKEN --value "YOUR_AGENT_PAT" > allowed: [copilot] > ``` > -> 2. **Via `assignees` or `reviewers` fields** (uses `COPILOT_GITHUB_TOKEN`): Use when creating new issues or PRs through workflows and want to assign the agent immediately. This is configured as part of `create-issue` or `create-pull-request` safe outputs and mirrors the [standard GitHub UI flow for assigning issues to Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot). +> 2. **Via `assignees` field in `create-issue`**: Use when creating new issues through workflows and want to assign the agent immediately. When `copilot` is in the assignees list, it's automatically filtered out and assigned via GraphQL in a separate step after issue creation (using the same token and API as method 1). > > ```yaml > safe-outputs: > create-issue: > assignees: copilot # or assignees: [copilot, user1] -> create-pull-request: -> reviewers: copilot # or reviewers: [copilot, user1] > ``` > -> For most workflows that create issues with agent assignments, use method 2 (`assignees: copilot`) as it's simpler and uses the existing `COPILOT_GITHUB_TOKEN`. Use method 1 (`assign-to-agent`) when you need to programmatically assign agents to issues that already exist or when you need fine-grained control over agent assignment operations. +> Both methods result in the same outcome as [manually assigning issues to Copilot through the GitHub UI](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot). Method 2 is simpler when creating issues, while method 1 provides fine-grained control for existing issues. +> +> **Technical Implementation**: Both methods use the GraphQL `replaceActorsForAssignable` mutation to assign the `copilot-swe-agent` bot to issues or PRs. The token precedence for both is: per-output β†’ global safe-outputs β†’ workflow-level β†’ `GH_AW_AGENT_TOKEN` (with fallback to `GH_AW_GITHUB_TOKEN` or `GITHUB_TOKEN` if not set). > > See [GitHub's official documentation on assigning issues to Copilot](https://docs.github.com/en/copilot/concepts/agents/coding-agent/about-coding-agent) for more details on the Copilot coding agent.