Add explicit GitHub MCP requirement warning for all engines in create-agentic-workflow.md

[Copilot]

Workflows created without the GitHub MCP server silently fail when trying to access GitHub API — engines cannot access api.github.com directly, regardless of what's in network: allowed:.

Changes

• Tools & MCP Servers section: Added ⚠️ GitHub API Access — All Engines warning block covering all engines (copilot, claude, codex, custom) with explicit correct/incorrect YAML examples:

  # ✅ CORRECT
  tools:
    github:
      mode: remote
      toolsets: [default]
  
  # ❌ WRONG — silently fails
  network:
    allowed:
      - api.github.com

• Quick Reference / Tools checklist: Added inline note on the GitHub API reads bullet reinforcing that tools: github: is required, not network: allowed:.

Warning is intentionally scoped to all engines (not just copilot) per review feedback.

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:

• https://api.github.com/graphql
  • Triggering command: /usr/bin/gh /usr/bin/gh api graphql -f query=query($owner: String!, $name: String!) { repository(owner: $owner, name: $name) { hasDiscussionsEnabled } } -f owner=github -f name=gh-aw (http block)
  • Triggering command: /usr/bin/gh /usr/bin/gh api graphql -f query=query($owner: String!, $name: String!) { repository(owner: $owner, name: $name) { hasDiscussionsEnabled } } -f owner=github -f name=gh-aw -pack /home/REDACTED/work/gh-aw/gh-aw/cmd/gh-aw/main.go (http block)
• https://api.github.com/repos/astral-sh/setup-uv/git/ref/tags/eac588ad8def6316056a12d4907a9d4d84ff7a3b
  • Triggering command: /usr/bin/gh gh api /repos/astral-sh/setup-uv/git/ref/tags/eac588ad8def6316056a12d4907a9d4d84ff7a3b --jq .object.sha (http block)
• https://api.github.com/repos/github/gh-aw/git/ref/tags/a70c5eada06553e3510ac27f2c3bda9d3705bccb
  • Triggering command: /usr/bin/gh gh api /repos/github/gh-aw/git/ref/tags/a70c5eada06553e3510ac27f2c3bda9d3705bccb --jq .object.sha (http block)
• https://api.github.com/repos/githubnext/agentics/git/ref/tags/
  • Triggering command: /usr/bin/gh gh api /repos/githubnext/agentics/git/ref/tags/# --jq .object.sha (http 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)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[plan] Strengthen GitHub MCP requirement guidance in create-agentic-workflow.md for Copilot engine</issue_title>
<issue_description>## Objective

Add an explicit, prominent callout in .github/aw/create-agentic-workflow.md clarifying that when the copilot engine is selected, GitHub MCP is required (not optional) for any GitHub API interaction — the Copilot engine cannot access api.github.com directly.

Context

From the Agent Persona Exploration (discussion github/gh-aw#19306), scenario BE2 (Webhook Error Triage) scored 3/5 partly because the instructions don't strongly enough emphasize that the Copilot engine cannot access api.github.com. This is identified as a "critical footgun": workflows that try to access api.github.com directly with the Copilot engine will silently fail. The AGENTS.md already contains this guidance but it isn't surfaced in the prompt used by the agentic workflow creator.

Approach

1. Open .github/aw/create-agentic-workflow.md
2. Locate the Tools & MCP Servers section (around line 228)
3. Add an explicit warning block like:

> ⚠️ **Copilot Engine + GitHub API**: The `copilot` engine **cannot access `api.github.com` directly**.
> When using `engine: copilot`, you **must** configure the GitHub MCP server for all GitHub API operations
> (creating issues, reading PRs, searching code, etc.). Omitting the GitHub MCP will cause silent failures.
> Example:
> ```yaml
> engine: copilot
> tools:
>   github:
>     mode: remote
>     toolsets: [default]
> ```

4. This warning should appear both in the engine selection guidance and in the GitHub MCP server configuration guidance.

Files to Modify

• .github/aw/create-agentic-workflow.md — add the callout in the Tools & MCP Servers section and near engine selection

Acceptance Criteria

• A clear warning is added near the engine selection or tools section stating Copilot engine requires GitHub MCP for GitHub API access
• An example YAML snippet shows correct configuration
• The warning contrasts correct vs incorrect approaches (GitHub MCP vs direct api.github.com)
• Lock file is recompiled: run make recompile after the markdown change

Generated by Plan Command for issue #discussion #19306

• expires on Mar 5, 2026, 4:03 AM UTC

Comments on the Issue (you are @copilot in this section)

@pelikhan @copilot Applicable to all engines, not just copilot.

• Fixes [plan] Strengthen GitHub MCP requirement guidance in create-agentic-workflow.md for Copilot engine #19322

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

[Copilot]

Pull request overview

Adds a prominent warning in the workflow-creation prompt clarifying that GitHub API operations should use the GitHub MCP configuration (tools: github:) rather than attempting direct access to api.github.com via network: allowed:.

Changes:

• Added a new “GitHub API Access” warning block in Tools & MCP Servers, including correct/incorrect YAML examples.
• Reinforced the guidance in the “Quick Reference / Tools checklist” section with an inline note.

Comments suppressed due to low confidence (2)

.github/aw/create-agentic-workflow.md:234

• The statement that all engines cannot access api.github.com directly, and that adding it to network: allowed: will NOT work, conflicts with existing repo docs/examples that explicitly allow api.github.com via network.allowed (e.g. .github/aw/github-agentic-workflows.md:1565-1600 shows network.allowed: ["api.github.com"]and thegithubecosystem includesapi.github.com). Please narrow this warning to the specific engine/constraint that actually applies (per AGENTS.md:135-160 this is a Copilot-engine limitation), or reword to clarify that GitHub MCP is the recommended/required mechanism for GitHub data access within the workflow agent, not that network allowlisting cannot reach the host at all.

   - ⚠️ **GitHub API Access — All Engines**: Agentic workflow engines (including `copilot`, `claude`, `codex`, and custom engines) **cannot access `api.github.com` directly**. For any GitHub API operations (reading issues, searching PRs, listing commits, checking runs, etc.), you **must** configure the GitHub MCP server via `tools: github:`. Adding `api.github.com` to `network: allowed:` will **NOT** work and will cause silent failures.

.github/aw/create-agentic-workflow.md:247

• The “❌ WRONG — Direct API access (will silently fail)” example is too absolute: network.allowed governs egress/firewall and is used elsewhere to permit curl https://api.github.com / GitHub-domain access. If the intent is “wrong as a substitute for GitHub MCP when you need authenticated GitHub API reads in the agent”, please say that explicitly (e.g., missing auth/tooling), rather than implying the host is unreachable even when allowlisted.

     - ❌ **WRONG** — Direct API access (will silently fail):
       ```yaml
       network:
         allowed:
           - api.github.com   # Does not grant API access to the engine
       ```

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

This checklist item repeats the claim that engines cannot access api.github.com directly. That contradicts the repo’s network-permissions guidance (e.g. .github/aw/github-agentic-workflows.md:1591-1599) and Copilot smoke tests that expect curl https://api.github.com` to succeed when GitHub domains are allowed. Recommend rephrasing to the specific limitation you’re documenting (e.g., “for GitHub API reads in workflows, prefer/require GitHub MCP tools rather than raw HTTP calls”).

This issue also appears in the following locations of the same file:

• line 234
• line 242

Suggested change

	- GitHub API reads → `tools: github: toolsets: [default]` (use toolsets, NOT allowed); ⚠️ engines cannot access `api.github.com` directly — GitHub MCP is required for all GitHub API operations
	- GitHub API reads → `tools: github: toolsets: [default]` (use toolsets, NOT `allowed`); ⚠️ for GitHub API operations in workflows, prefer using the GitHub MCP tools (github toolsets) rather than raw HTTP calls, even when `api.github.com` is reachable via `network: allowed: [...]`