Network Configuration Guide

This guide provides practical examples for configuring network access in GitHub Agentic Workflows while maintaining security.

Quick Start

Configure network access by adding ecosystem identifiers to the network.allowed list. Always include defaults for basic infrastructure:

network:
  allowed:
    - defaults      # Required: Basic infrastructure
    - python        # PyPI, conda (for Python projects)
    - node          # npm, yarn, pnpm (for Node.js projects)
    - go            # Go module proxy (for Go projects)
    - containers    # Docker Hub, GHCR (for container projects)

Available Ecosystems

Ecosystem	Includes	Use For
defaults	Certificates, JSON schema, Ubuntu mirrors	All workflows (required)
python	PyPI, conda, pythonhosted.org	Python packages
node	npm, yarn, pnpm, Node.js	JavaScript/TypeScript
go	proxy.golang.org, sum.golang.org	Go modules
containers	Docker Hub, GHCR, Quay, GCR, MCR	Container images
java	Maven, Gradle	Java dependencies
dotnet	NuGet	.NET packages
ruby	RubyGems, Bundler	Ruby gems
rust	crates.io	Rust crates
github	githubusercontent.com	GitHub resources
terraform	HashiCorp registry	Terraform modules
playwright	Browser downloads	Web testing
linux-distros	Debian, Ubuntu, Alpine	Linux packages

Common Configuration Patterns

# Python project with containers
network:
  allowed:
    - defaults
    - python
    - containers

# Full-stack web development
network:
  allowed:
    - defaults
    - node
    - playwright
    - github

# DevOps automation
network:
  allowed:
    - defaults
    - terraform
    - containers
    - github

Custom Domains

Add specific domains for your services. Both base domains and wildcard patterns are supported:

network:
  allowed:
    - defaults
    - python
    - "api.example.com"        # Matches api.example.com and subdomains
    - "*.cdn.example.com"      # Wildcard: matches any subdomain of cdn.example.com

Wildcard pattern behavior:

• *.example.com matches sub.example.com, deep.nested.example.com, and example.com
• Only single wildcards at the start are supported (e.g., *.*.example.com is invalid)

Tip

Both example.com and *.example.com match subdomains. Use wildcards when you want to explicitly document that subdomain access is expected.

Protocol-Specific Filtering

Restrict domains to specific protocols for enhanced security (Copilot engine with AWF firewall):

engine: copilot
network:
  allowed:
    - defaults
    - "https://secure.api.example.com"   # HTTPS-only
    - "http://legacy.internal.com"       # HTTP-only
    - "example.org"                      # Both protocols (default)
sandbox:
  agent: awf  # Firewall enabled

Validation: Invalid protocols (e.g., ftp://) are rejected at compile time.

See Network Permissions - Protocol-Specific Filtering for complete details.

Strict Mode and Ecosystem Identifiers

Workflows use strict mode by default, which enforces ecosystem identifiers instead of individual domains for security. This applies to all engines.

# ✗ Rejected in strict mode
network:
  allowed:
    - "pypi.org"       # Error: use 'python' ecosystem instead
    - "npmjs.org"      # Error: use 'node' ecosystem instead

# ✓ Accepted in strict mode
network:
  allowed:
    - python           # Ecosystem identifier
    - node             # Ecosystem identifier

Error Messages

When strict mode rejects a domain that belongs to a known ecosystem, the error message suggests the ecosystem identifier:

error: strict mode: network domains must be from known ecosystems (e.g., 'defaults',
'python', 'node') for all engines in strict mode. Custom domains are not allowed for
security. Did you mean: 'pypi.org' belongs to ecosystem 'python'?

When strict mode rejects a custom domain:

error: strict mode: network domains must be from known ecosystems (e.g., 'defaults',
'python', 'node') for all engines in strict mode. Custom domains are not allowed for
security. Set 'strict: false' to use custom domains.

Using Custom Domains

To use custom domains (domains not in known ecosystems), disable strict mode:

---
strict: false    # Required for custom domains
network:
  allowed:
    - python           # Ecosystem identifier
    - "api.example.com"  # Custom domain (only allowed with strict: false)
---

Security Note: Custom domains bypass ecosystem validation. Only disable strict mode when necessary and ensure you trust the custom domains you allow.

Security Best Practices

1. Start minimal - Only add ecosystems you actually use
2. Use ecosystem identifiers - Don’t list individual domains (use python instead of pypi.org, files.pythonhosted.org, etc.)
3. Keep strict mode enabled - Provides enhanced security validation (enabled by default)
4. Add incrementally - Start with defaults, add ecosystems as needed based on firewall denials

Troubleshooting Firewall Blocking

View firewall activity with gh aw logs --run-id <run-id> to identify blocked domains:

 Firewall Log Analysis
Blocked Domains:
  ✗ registry.npmjs.org:443 (3 requests) → Add `node` ecosystem
  ✗ pypi.org:443 (2 requests) → Add `python` ecosystem

Common mappings: npm/Node.js → node, PyPI/Python → python, Docker → containers, Go modules → go.

Advanced Options

Disable all external network access (engine communication still allowed):

network: {}

View complete ecosystem domain lists in the ecosystem domains source.

Related Documentation

• Network Permissions Reference - Complete network configuration reference
• Security Guide - Security best practices
• Troubleshooting - Common issues and solutions