From d39377cecc21930653bde76ca390502e7b68699e Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Sun, 15 Mar 2026 19:18:33 +0000 Subject: [PATCH] docs: add gh aw domains command and safe-outputs.allowed-url-domains Document two user-facing features merged on 2026-03-15 after DDUw's 04:31 UTC scan: - gh aw domains (PR #21086): new CLI command to list effective network domains for each workflow, including ecosystem-expanded domains and engine defaults. Added to the Monitoring section of cli.md. - safe-outputs.allowed-url-domains (PR #21083): new safe-outputs field that additively extends the URL sanitization domain allowlist (unions with the engine/network base set). Distinct from allowed-domains, which replaces the default set. Updated the Text Sanitization section of safe-outputs.md. Co-Authored-By: Claude Sonnet 4.6 --- docs/src/content/docs/reference/safe-outputs.md | 15 +++++++++++++-- docs/src/content/docs/setup/cli.md | 14 ++++++++++++++ 2 files changed, 27 insertions(+), 2 deletions(-) diff --git a/docs/src/content/docs/reference/safe-outputs.md b/docs/src/content/docs/reference/safe-outputs.md index 958ac2bac3..1a97fed11a 100644 --- a/docs/src/content/docs/reference/safe-outputs.md +++ b/docs/src/content/docs/reference/safe-outputs.md @@ -1404,7 +1404,7 @@ safe-outputs: Accepts a plain string or an object with `name` and optional `url`, consistent with the top-level `environment:` syntax. -### Text Sanitization (`allowed-domains:`, `allowed-github-references:`) +### Text Sanitization (`allowed-domains:`, `allowed-url-domains:`, `allowed-github-references:`) The text output by AI agents is automatically sanitized to prevent injection of malicious content and ensure safe rendering on GitHub. The auto-sanitization applied is: XML escaped, HTTPS only, domain allowlist (GitHub by default), 0.5MB/65k line limits, control char stripping. @@ -1416,7 +1416,18 @@ safe-outputs: allowed-github-references: [] # Escape all GitHub references ``` -**Domain Filtering** (`allowed-domains`): Controls which domains are allowed in URLs. URLs from other domains are replaced with `(redacted)`. +**Domain Filtering** (`allowed-domains`): Controls which domains are allowed in URLs. URLs from other domains are replaced with `(redacted)`. This field **replaces** the default domain set (GitHub domains are always retained, but engine and network defaults are not applied). + +**Additive Domain Filtering** (`allowed-url-domains`): Extends the domain allowlist **additively** — unions extra domains with the engine and `network.allowed` base set rather than replacing it. Supports the same ecosystem identifiers as `network.allowed` (e.g., `node`, `python`). Use this when you want to allow additional domains in sanitized output without losing the defaults already provided by your network configuration: + +```yaml wrap +safe-outputs: + allowed-url-domains: + - "docs.example.com" # Allow this domain in addition to engine defaults + - python # Ecosystem identifier — adds all Python/PyPI domains +``` + +`allowed-domains` and `allowed-url-domains` are mutually exclusive: if `allowed-domains` is set it takes full precedence and `allowed-url-domains` is ignored. **Reference Escaping** (`allowed-github-references`): Controls which GitHub repository references (`#123`, `owner/repo#456`) are allowed in workflow output. When configured, references to unlisted repositories are escaped with backticks to prevent GitHub from creating timeline items. This is particularly useful for [SideRepoOps](/gh-aw/patterns/side-repo-ops/) workflows to prevent automation from cluttering your main repository's timeline. diff --git a/docs/src/content/docs/setup/cli.md b/docs/src/content/docs/setup/cli.md index 5b420f69dc..4805f4ef74 100644 --- a/docs/src/content/docs/setup/cli.md +++ b/docs/src/content/docs/setup/cli.md @@ -407,6 +407,20 @@ gh aw health issue-monster --days 90 # 90-day metrics for workflow Shows success/failure rates, trend indicators (↑ improving, → stable, ↓ degrading), execution duration, token usage, costs, and alerts when success rate drops below threshold. +#### `domains` + +List network domains configured in agentic workflows. Without a workflow argument, lists all workflows with a summary of their allowed and blocked domain counts. When a workflow is specified, lists all effective domains for that workflow—including domains expanded from ecosystem identifiers (e.g., `node`, `python`, `github`) and engine defaults. + +```bash wrap +gh aw domains # List all workflows with domain count summary +gh aw domains weekly-research # List effective domains for a workflow +gh aw domains weekly-research --json # Output in JSON format +``` + +The workflow argument accepts a workflow ID (basename without `.md`, e.g., `weekly-research`) or a file path (e.g., `weekly-research.md` or `.github/workflows/weekly-research.md`). Use this command to verify that your `network:` configuration expands to the intended set of domains before deploying a workflow. + +**Options:** `--json` + ### Management #### `enable`