From ce9b5095c2ab27ca11d9b10d3a905ba8517ff197 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 21 Mar 2026 05:26:50 +0000 Subject: [PATCH 1/2] Initial plan From 95afcc832ab04438f82ea2071b6379ce9e420095 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 21 Mar 2026 05:35:52 +0000 Subject: [PATCH 2/2] Add network.md documentation and link from agentic-workflows agent Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> Agent-Logs-Url: https://github.com/github/gh-aw/sessions/b5cee0f8-8575-4cc8-974b-673ca058f755 --- .github/agents/agentic-workflows.agent.md | 1 + .github/aw/network.md | 176 ++++++++++++++++++++++ 2 files changed, 177 insertions(+) create mode 100644 .github/aw/network.md diff --git a/.github/agents/agentic-workflows.agent.md b/.github/agents/agentic-workflows.agent.md index c0f21877e1b..8454ad9e67b 100644 --- a/.github/agents/agentic-workflows.agent.md +++ b/.github/agents/agentic-workflows.agent.md @@ -174,4 +174,5 @@ gh aw compile --validate - Workflows must be compiled to `.lock.yml` files before running in GitHub Actions - **Bash tools are enabled by default** - Don't restrict bash commands unnecessarily since workflows are sandboxed by the AWF - Follow security best practices: minimal permissions, explicit network access, no template injection +- **Network configuration**: Use ecosystem identifiers (`node`, `python`, `go`, etc.) or explicit FQDNs in `network.allowed`. Bare shorthands like `npm` or `pypi` are **not** valid. See https://github.com/github/gh-aw/blob/main/.github/aw/network.md for the full list of valid ecosystem identifiers and domain patterns. - **Single-file output**: When creating a workflow, produce exactly **one** workflow `.md` file. Do not create separate documentation files (architecture docs, runbooks, usage guides, etc.). If documentation is needed, add a brief `## Usage` section inside the workflow file itself. diff --git a/.github/aw/network.md b/.github/aw/network.md new file mode 100644 index 00000000000..c20ee3e9ed7 --- /dev/null +++ b/.github/aw/network.md @@ -0,0 +1,176 @@ +--- +description: Network access configuration reference for gh-aw workflows — valid ecosystem identifiers, domain patterns, and common mistakes to avoid. +--- + +# Network Access Configuration + +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). + +## Quick Reference + +```yaml +# Shorthand — use default infrastructure domains only +network: defaults + +# Custom — allow defaults plus package registries for a Node.js project +network: + allowed: + - defaults + - node + +# Custom — allow specific external APIs +network: + allowed: + - defaults + - api.example.com + - "*.trusted-partner.com" + +# No network access +network: + allowed: [] +``` + +## Valid Values for `network.allowed` + +Each entry in `network.allowed` must be one of: + +| Type | Examples | Notes | +|---|---|---| +| **Ecosystem identifier** | `defaults`, `node`, `python` | Expands to a curated list of domains for that runtime/tool | +| **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. + +## Ecosystem Identifiers + +These keywords expand to curated lists of domains maintained by gh-aw: + +| Identifier | Runtime / Tool | Key Domains Enabled | +|---|---|---| +| `defaults` | Basic infrastructure | Certificate authorities, Ubuntu package verification, JSON schema | +| `github` | GitHub domains | `*.githubusercontent.com`, `codeload.github.com`, `docs.github.com` | +| `github-actions` | GitHub Actions artifacts | Azure Blob storage for action caches and artifacts | +| `node` | npm / yarn / pnpm | `registry.npmjs.org`, `npmjs.com`, `yarnpkg.com` | +| `python` | pip / PyPI / conda | `pypi.org`, `files.pythonhosted.org`, `pip.pypa.io` | +| `go` | Go modules | `proxy.golang.org`, `sum.golang.org`, `go.dev` | +| `dotnet` | NuGet / .NET | `api.nuget.org`, `nuget.org`, `dotnet.microsoft.com` | +| `java` | Maven / Gradle | `repo1.maven.org`, `plugins.gradle.org`, `jdk.java.net` | +| `ruby` | Bundler / RubyGems | `rubygems.org`, `api.rubygems.org` | +| `rust` | Cargo | `crates.io`, `index.crates.io`, `static.crates.io`, `sh.rustup.rs` | +| `swift` | Swift Package Manager | `swift.org`, `cocoapods.org` | +| `php` | Composer / Packagist | `packagist.org`, `repo.packagist.org`, `getcomposer.org` | +| `dart` | pub.dev | `pub.dev`, `pub.dartlang.org` | +| `haskell` | Hackage / GHCup | `*.hackage.haskell.org`, `get-ghcup.haskell.org` | +| `perl` | CPAN | `cpan.org`, `metacpan.org` | +| `containers` | Docker / GHCR | `ghcr.io`, `registry.hub.docker.com`, `*.docker.io` | +| `playwright` | Playwright browsers | `playwright.download.prss.microsoft.com`, `cdn.playwright.dev` | +| `linux-distros` | apt / yum / apk | `deb.debian.org`, `security.debian.org`, Ubuntu/Alpine mirrors | +| `terraform` | HashiCorp | `releases.hashicorp.com`, `registry.terraform.io` | +| `local` | Loopback addresses | `127.0.0.1`, `::1`, `localhost` | +| `bazel` | Bazel build | `releases.bazel.build`, `bcr.bazel.build` | +| `clojure` | Clojure / Clojars | `clojars.org`, `repo.clojars.org` | +| `deno` | Deno / JSR | `deno.land`, `jsr.io` | +| `elixir` | Hex.pm | `hex.pm`, `repo.hex.pm` | +| `fonts` | Google Fonts | `fonts.googleapis.com`, `fonts.gstatic.com` | +| `julia` | Julia packages | `pkg.julialang.org`, `julialang.org` | +| `kotlin` | Kotlin / JetBrains | `packages.jetbrains.team` | +| `lua` | LuaRocks | `luarocks.org` | +| `node-cdns` | JS CDNs | `cdn.jsdelivr.net`, `code.jquery.com`, `unpkg.com` | +| `ocaml` | OPAM | `opam.ocaml.org`, `ocaml.org` | +| `powershell` | PowerShell Gallery | `powershellgallery.com` | +| `r` | CRAN | `cran.r-project.org`, `cloud.r-project.org` | +| `scala` | sbt / Scala | `repo.scala-sbt.org`, `repo1.maven.org` | +| `zig` | Zig packages | `ziglang.org` | +| `dev-tools` | CI/CD tools | Renovate, Codecov, shields.io, and other dev tooling | +| `chrome` | Chrome / Chromium | `*.googleapis.com`, `*.gvt1.com` | + +## Invalid Shorthands + +These values look like they might work but are **not valid** ecosystem identifiers and will be passed through as literal domain names (and will almost certainly not match any real host): + +| Invalid value | What you probably meant | Correct value | +|---|---|---| +| `npm` | npm registry | `node` | +| `pypi` | Python Package Index | `python` | +| `pip` | pip package manager | `python` | +| `cargo` | Rust crate registry | `rust` | +| `gem` or `gems` | RubyGems | `ruby` | +| `nuget` | NuGet package registry | `dotnet` | +| `maven` | Maven Central | `java` | +| `gradle` | Gradle plugins | `java` | +| `composer` | PHP Composer | `php` | +| `docker` | Docker Hub / GHCR | `containers` | +| `localhost` | Loopback interface | `local` | + +## Domain Pattern Rules + +- **Wildcard `*` requires a dot prefix**: `*.example.com` is valid; bare `*` is blocked (and rejected outright in strict mode). +- **Protocol prefix is not supported**: `https://api.example.com` is not a valid entry — omit the scheme and write `api.example.com`. +- **Subdomains must be explicit**: `github.com` does not cover `api.github.com`; use `*.github.com` or add both entries. + +## Inferring the Right Ecosystem From Repository Files + +When a workflow builds, tests, or installs packages, always add the matching ecosystem alongside `defaults`: + +| File indicators | Ecosystem to add | Enables | +|---|---|---| +| `package.json`, `yarn.lock`, `pnpm-lock.yaml`, `.nvmrc` | `node` | `registry.npmjs.org` | +| `requirements.txt`, `pyproject.toml`, `uv.lock`, `Pipfile` | `python` | `pypi.org`, `files.pythonhosted.org` | +| `go.mod`, `go.sum` | `go` | `proxy.golang.org`, `sum.golang.org` | +| `*.csproj`, `*.sln`, `*.slnx` | `dotnet` | `api.nuget.org` | +| `pom.xml`, `build.gradle` | `java` | `repo1.maven.org` | +| `Gemfile`, `*.gemspec` | `ruby` | `rubygems.org` | +| `Cargo.toml` | `rust` | `crates.io` | +| `Package.swift` | `swift` | `swift.org` | +| `composer.json` | `php` | `packagist.org` | +| `pubspec.yaml` | `dart` | `pub.dev` | + +> ⚠️ **`network: defaults` alone is never sufficient for code workflows** — `defaults` covers basic infrastructure (certificate authorities, Ubuntu verification) but cannot reach package registries. Always add the language ecosystem identifier. + +## Common Patterns + +### Workflow that reads GitHub data only + +```yaml +network: + allowed: + - defaults + - github +``` + +### Node.js CI workflow + +```yaml +network: + allowed: + - defaults + - node +``` + +### Multi-language project + +```yaml +network: + allowed: + - defaults + - node + - python +``` + +### Calling an external API + +```yaml +network: + allowed: + - defaults + - api.myservice.com + - "*.myservice.com" +``` + +### No outbound network access + +```yaml +network: + allowed: [] +```