diff --git a/docs/src/content/docs/reference/network.md b/docs/src/content/docs/reference/network.md index 5e8fc1761c..63df56a352 100644 --- a/docs/src/content/docs/reference/network.md +++ b/docs/src/content/docs/reference/network.md @@ -94,7 +94,10 @@ Mix ecosystem identifiers with specific domains for fine-grained control: | Identifier | Includes | |------------|----------| | `defaults` | Basic infrastructure (certificates, JSON schema, Ubuntu, package mirrors) | -| `github` | GitHub domains | +| `github` | GitHub domains (`github.com`, `docs.github.com`, `github.blog`, `*.githubusercontent.com`, and related) | +| `local` | Loopback addresses (`localhost`, `127.0.0.1`, `::1`) | +| `dev-tools` | Popular CI/CD and developer tool services (Codecov, Shields.io, Snyk, Renovate, CircleCI, etc.) | +| `default-safe-outputs` | Compound: `defaults` + `dev-tools` + `github` + `local` — recommended baseline for `safe-outputs.allowed-domains` | | `containers` | Docker Hub, GitHub Container Registry, Quay | | `linux-distros` | Debian, Alpine, and other Linux package repositories | | `dotnet`, `dart`, `go`, `haskell`, `java`, `julia`, `node`, `perl`, `php`, `python`, `ruby`, `rust`, `swift` | Language-specific package managers and registries | diff --git a/docs/src/content/docs/reference/safe-outputs.md b/docs/src/content/docs/reference/safe-outputs.md index b38efc8867..a3ef9091a2 100644 --- a/docs/src/content/docs/reference/safe-outputs.md +++ b/docs/src/content/docs/reference/safe-outputs.md @@ -1425,7 +1425,21 @@ 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)`. Accepts specific domain strings or [ecosystem identifiers](/gh-aw/reference/network/#ecosystem-identifiers): + +```yaml wrap +safe-outputs: + # Allow specific domains + allowed-domains: [api.example.com, "*.storage.example.com"] + + # Use ecosystem identifiers + allowed-domains: [default-safe-outputs] # defaults + dev-tools + github + local + + # Mix identifiers and custom domains + allowed-domains: [default-safe-outputs, api.example.com] +``` + +The `default-safe-outputs` compound ecosystem is the recommended baseline — it covers infrastructure certificates (`defaults`), GitHub domains (`github`), popular developer tooling (`dev-tools`), and loopback addresses (`local`). **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.