Add network.allowed reference docs and link from agentic-workflows agent

[Copilot]

Bare shorthands like npm or pypi in network.allowed are silently treated as literal domain names (which never match), causing subtle failures. There was no authoritative reference for what values are actually valid.

Changes

• .github/aw/network.md (new) — complete network.allowed reference:

  • All 37 supported ecosystem identifiers with their key resolved domains (sourced from pkg/workflow/data/ecosystem_domains.json)
  • Explicit invalid-shorthands table mapping common mistakes to correct values (npm → node, pypi → python, localhost → local, etc.)
  • Domain pattern rules (wildcard format, no protocol prefix, subdomain scoping)
  • Ecosystem auto-detection table: repo file indicators → correct identifier
  • Ready-to-use YAML examples

• .github/agents/agentic-workflows.agent.md — adds a Network configuration note in Important Notes, calling out invalid shorthands and linking to the new reference

Example of what this clarifies

# ❌ Invalid — "npm" is not a recognized identifier; treated as a literal domain
network:
  allowed:
    - npm

# ✅ Correct — "node" expands to registry.npmjs.org, yarnpkg.com, etc.
network:
  allowed:
    - defaults
    - node

---

💬 Send tasks to Copilot coding agent from Slack and Teams to turn conversations into code. Copilot posts an update in your thread when it's finished.

[Copilot]

Pull request overview

Adds an authoritative network.allowed reference doc for gh-aw workflows and links to it from the agentic-workflows agent guidance to prevent misconfiguration (e.g., using npm/pypi shorthands that don’t expand).

Changes:

• Introduces a new .github/aw/network.md reference covering valid network.allowed values, ecosystem identifiers, wildcard rules, and common invalid shorthands.
• Updates .github/agents/agentic-workflows.agent.md with a Network configuration note and link to the new reference.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 7 comments.

File	Description
.github/aw/network.md	New reference documentation for network.allowed, including identifiers, patterns, and examples.
.github/agents/agentic-workflows.agent.md	Adds a reminder/link in “Important Notes” to steer users away from invalid shorthands.

---

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

[Copilot]

This bullet says protocol prefixes aren’t supported, but network.allowed currently allows http:// and https:// prefixes for protocol-specific filtering (see pkg/workflow/safe_outputs_validation.go:121-141 and the existing reference docs at docs/src/content/docs/reference/network.md#protocol-specific-domain-filtering). Please update this rule to reflect current supported syntax.

Suggested change

	- **Protocol prefix is not supported**: `https://api.example.com` is not a valid entry — omit the scheme and write `api.example.com`.
	- **Optional `http://` or `https://` prefix only**: `api.example.com`, `https://api.example.com`, and `http://api.example.com` are all valid entries; other schemes (for example, `ws://`, `wss://`, `ftp://`) are not supported.

[Copilot]

This rule says github.com does not cover api.github.com, but gh-aw treats an allowed base domain as allowing all its subdomains (and the official docs state the same). Please correct this to avoid readers over-permitting with unnecessary wildcards or duplicating entries.

Suggested change

	- **Subdomains must be explicit**: `github.com` does not cover `api.github.com`; use `*.github.com` or add both entries.
	- **Base domains also cover subdomains**: allowing `github.com` also allows `api.github.com`; you do not need `*.github.com` or duplicate entries.

[Copilot]

This bullet implies bare * is blocked, but * is treated as an allow-all sentinel outside strict mode (validation explicitly skips it), and strict mode only rejects standalone * entries. Consider updating this guidance to distinguish: * (allow all; discouraged; rejected in strict mode) vs *.example.com (scoped wildcard).

Suggested change

	- **Wildcard `*` requires a dot prefix**: `*.example.com` is valid; bare `*` is blocked (and rejected outright in strict mode).
	- **Wildcard usage**: `*.example.com` is a valid scoped wildcard. A bare `*` acts as an allow-all sentinel outside strict mode (discouraged) and is rejected outright in strict mode.

[Copilot]

The doc says all traffic is enforced by the Agent Workflow Firewall (AWF), but gh-aw can run with the firewall/sandbox disabled (e.g., sandbox.agent: false / deprecated network.firewall: false). In those cases network.allowed still affects URL sanitization but not egress enforcement—please soften/clarify this sentence so readers don’t assume enforcement is guaranteed.

Suggested change

	Use the `network` frontmatter field to control which domains an AI engine can reach during a workflow run. All traffic is enforced by the Agent Workflow Firewall (AWF).
	Use the `network` frontmatter field to control which domains an AI engine can reach during a workflow run. When the Agent Workflow Firewall (AWF) is enabled, it enforces these settings for outbound traffic; when disabled, this configuration still affects URL sanitization but does not itself guarantee network egress enforcement.

[Copilot]

“Exact domain” entries aren’t limited to FQDNs in the current implementation (single-label hostnames like localhost and IP literals like 127.0.0.1 are accepted/used). Consider rewording this row to “hostname/domain (no scheme; may be single-label like localhost)” to match actual validation behavior.

Suggested change

	| **Exact domain** | `api.example.com`, `registry.npmjs.org` | Must be a fully-qualified domain name (FQDN) |
	| **Wildcard subdomain** | `*.example.com` | Matches `sub.example.com`, `deep.nested.example.com`, and `example.com` itself |
	> ⚠️ **Bare shorthands like `npm`, `pypi`, or `localhost` are NOT valid** unless they are listed in the ecosystem identifiers table below. Use ecosystem identifiers (`node`, `python`) or explicit FQDNs (`registry.npmjs.org`, `pypi.org`) instead.
	| **Hostname / domain** | `api.example.com`, `registry.npmjs.org`, `localhost`, `127.0.0.1` | Hostname or domain (no scheme); may be single-label (like `localhost`) or an IP literal |
	| **Wildcard subdomain** | `*.example.com` | Matches `sub.example.com`, `deep.nested.example.com`, and `example.com` itself |
	> ⚠️ **Bare ecosystem-like shorthands such as `npm` or `pypi` are NOT valid** unless they are listed in the ecosystem identifiers table below. Use ecosystem identifiers (`node`, `python`) or explicit hostnames/domains (`registry.npmjs.org`, `pypi.org`, `localhost`) instead.

[Copilot]

This warning groups localhost with invalid shorthands. However localhost is a valid explicit allowed entry today (it will match requests to the localhost hostname); what’s not supported is using it as an ecosystem identifier, and it won’t cover 127.0.0.1/::1. Suggest reframing to “localhost is not an ecosystem identifier; prefer local if you want to allow all loopback forms.”

Suggested change

	> ⚠️ **Bare shorthands like `npm`, `pypi`, or `localhost` are NOT valid** unless they are listed in the ecosystem identifiers table below. Use ecosystem identifiers (`node`, `python`) or explicit FQDNs (`registry.npmjs.org`, `pypi.org`) instead.
	> ⚠️ **Bare shorthands like `npm` or `pypi` are NOT valid ecosystem identifiers unless they are listed in the ecosystem identifiers table below. `localhost` is not an ecosystem identifier; prefer `local` if you want to allow all loopback forms.** Use ecosystem identifiers (`node`, `python`) or explicit FQDNs (`registry.npmjs.org`, `pypi.org`) instead.

[Copilot]

The table claims to list all supported ecosystem identifiers, but it’s missing the supported compound identifier default-safe-outputs (see pkg/workflow/domains.go compoundEcosystems) which also expands via the same mechanism as network.allowed. Either include it (with a note it’s primarily intended for safe-outputs.allowed-domains) or adjust the “complete list” wording/count.