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..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**: Pre-assigns to `@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 040c541c6d..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 `@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 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 `@copilot` 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) 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) 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 pre-assigned to `@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 `@copilot` 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 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 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 6c6b9cf45e..2229981d5a 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`). +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. @@ -801,6 +801,21 @@ 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 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: +> create-issue: +> assignees: copilot # Assigns agent when creating issue +> ``` +> +> **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:`) Assigns users to issues. Restrict with `allowed` list. Target: `"triggering"` (issue event), `"*"` (any), or number. Supports single or multiple assignees. @@ -900,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 7e4811a030..24710e43ed 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**: @@ -358,6 +358,34 @@ 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. **Both methods use the same token (`GH_AW_AGENT_TOKEN`) and GraphQL API** to perform the assignment: +> +> 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: +> assign-to-agent: +> name: "copilot" +> allowed: [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] +> ``` +> +> 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. + > [!NOTE] > Resource owner requirements > The token's resource owner must match the repository ownership: