Skip to content

Commit bc9f095

Browse files
CopilotCopilot
authored
Document network ecosystem identifiers for package registries and CDNs (#7417)
1 parent 87bd7f6 commit bc9f095

File tree

10 files changed

+22495
-2
lines changed

10 files changed

+22495
-2
lines changed

‎docs/src/content/docs/guides/network-configuration.md‎

Lines changed: 390 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,390 @@
1+
---
2+
title: Network Configuration Guide
3+
description: Common network configurations for package registries, CDNs, and development tools
4+
sidebar:
5+
order: 450
6+
---
7+
8+
This guide provides practical examples and best practices for configuring network access in GitHub Agentic Workflows. Use these patterns to reduce firewall denials while maintaining security.
9+
10+
## Quick Start
11+
12+
If you're experiencing firewall denials for legitimate package installations or dependency resolution, start with these common configurations:
13+
14+
### Python Projects
15+
16+
```yaml
17+
network:
18+
allowed:
19+
- defaults # Basic infrastructure
20+
- python # PyPI and conda registries
21+
```
22+
23+
The `python` ecosystem includes:
24+
- `pypi.org` - Python Package Index
25+
- `files.pythonhosted.org` - PyPI file hosting
26+
- `pip.pypa.io` - pip installer
27+
- `*.pythonhosted.org` - PyPI CDN domains
28+
- `anaconda.org` - Conda packages
29+
- Additional Python ecosystem domains
30+
31+
### Node.js Projects
32+
33+
```yaml
34+
network:
35+
allowed:
36+
- defaults # Basic infrastructure
37+
- node # npm, yarn, pnpm, and Node.js
38+
```
39+
40+
The `node` ecosystem includes:
41+
- `registry.npmjs.org` - npm registry
42+
- `npmjs.com` - npm website
43+
- `nodejs.org` - Node.js downloads
44+
- `yarnpkg.com` - Yarn package manager
45+
- `get.pnpm.io` - pnpm installer
46+
- `bun.sh` - Bun runtime
47+
- `deno.land` - Deno runtime
48+
- Additional Node.js ecosystem domains
49+
50+
### Go Projects
51+
52+
```yaml
53+
network:
54+
allowed:
55+
- defaults # Basic infrastructure
56+
- go # Go module proxy and registries
57+
```
58+
59+
The `go` ecosystem includes:
60+
- `proxy.golang.org` - Go module proxy
61+
- `sum.golang.org` - Go checksum database
62+
- `go.dev` - Go documentation
63+
- `golang.org` - Go language site
64+
- `pkg.go.dev` - Package documentation
65+
66+
### Docker/Container Projects
67+
68+
```yaml
69+
network:
70+
allowed:
71+
- defaults # Basic infrastructure
72+
- containers # Docker Hub, GHCR, Quay, etc.
73+
```
74+
75+
The `containers` ecosystem includes:
76+
- `registry.hub.docker.com` - Docker Hub
77+
- `*.docker.io` - Docker domains
78+
- `ghcr.io` - GitHub Container Registry
79+
- `quay.io` - Quay container registry
80+
- `gcr.io` - Google Container Registry
81+
- `mcr.microsoft.com` - Microsoft Container Registry
82+
- Additional container registry domains
83+
84+
## Multi-Language Projects
85+
86+
For projects using multiple languages or tools, combine ecosystem identifiers:
87+
88+
```yaml
89+
network:
90+
allowed:
91+
- defaults # Basic infrastructure
92+
- python # Python dependencies
93+
- node # JavaScript dependencies
94+
- containers # Docker images
95+
```
96+
97+
## Full-Stack Development
98+
99+
A comprehensive configuration for full-stack development with multiple tools:
100+
101+
```yaml
102+
network:
103+
allowed:
104+
- defaults # Basic infrastructure
105+
- github # GitHub API and resources
106+
- node # npm, yarn, pnpm
107+
- python # PyPI, conda
108+
- containers # Docker registries
109+
- playwright # Browser testing
110+
```
111+
112+
## Language-Specific Configurations
113+
114+
### .NET Projects
115+
116+
```yaml
117+
network:
118+
allowed:
119+
- defaults
120+
- dotnet # NuGet and .NET ecosystem
121+
```
122+
123+
Includes: `nuget.org`, `dotnet.microsoft.com`, `api.nuget.org`, and related domains.
124+
125+
### Java Projects
126+
127+
```yaml
128+
network:
129+
allowed:
130+
- defaults
131+
- java # Maven, Gradle, and Java registries
132+
```
133+
134+
Includes: `repo.maven.apache.org`, `gradle.org`, `repo1.maven.org`, and related domains.
135+
136+
### Ruby Projects
137+
138+
```yaml
139+
network:
140+
allowed:
141+
- defaults
142+
- ruby # RubyGems and Bundler
143+
```
144+
145+
Includes: `rubygems.org`, `api.rubygems.org`, `bundler.rubygems.org`, and related domains.
146+
147+
### Rust Projects
148+
149+
```yaml
150+
network:
151+
allowed:
152+
- defaults
153+
- rust # Crates.io and Cargo
154+
```
155+
156+
Includes: `crates.io`, `static.crates.io`, `static.rust-lang.org`, and related domains.
157+
158+
## Infrastructure and Platform Tools
159+
160+
### Terraform/HashiCorp
161+
162+
```yaml
163+
network:
164+
allowed:
165+
- defaults
166+
- terraform # Terraform registry and HashiCorp
167+
```
168+
169+
### Linux Package Managers
170+
171+
```yaml
172+
network:
173+
allowed:
174+
- defaults
175+
- linux-distros # Debian, Ubuntu, Alpine, etc.
176+
```
177+
178+
## Custom Domains
179+
180+
Add specific domains alongside ecosystem identifiers:
181+
182+
```yaml
183+
network:
184+
allowed:
185+
- defaults
186+
- python
187+
- "api.example.com" # Your API
188+
- "cdn.example.com" # Your CDN
189+
```
190+
191+
:::tip
192+
Domain matching is automatic for subdomains. Listing `example.com` allows access to all subdomains like `api.example.com`, `cdn.example.com`, etc.
193+
:::
194+
195+
## Testing and Browser Automation
196+
197+
For workflows using Playwright or web testing:
198+
199+
```yaml
200+
network:
201+
allowed:
202+
- defaults
203+
- playwright # Playwright browser downloads
204+
- node # npm dependencies
205+
- "*.example.com" # Sites to test
206+
```
207+
208+
## Security Best Practices
209+
210+
### Start Minimal
211+
212+
Begin with only the ecosystems you need:
213+
214+
```yaml
215+
# ✅ Good: Only what's needed
216+
network:
217+
allowed:
218+
- defaults
219+
- python
220+
```
221+
222+
```yaml
223+
# ❌ Avoid: Too permissive
224+
network:
225+
allowed:
226+
- defaults
227+
- python
228+
- node
229+
- java
230+
- dotnet
231+
- ruby
232+
- rust
233+
# ... when you only use Python
234+
```
235+
236+
### Use Ecosystem Identifiers
237+
238+
Prefer ecosystem identifiers over individual domains:
239+
240+
```yaml
241+
# ✅ Good: Use ecosystem identifier
242+
network:
243+
allowed:
244+
- python
245+
```
246+
247+
```yaml
248+
# ❌ Avoid: Listing individual domains
249+
network:
250+
allowed:
251+
- "pypi.org"
252+
- "files.pythonhosted.org"
253+
- "pip.pypa.io"
254+
- "bootstrap.pypa.io"
255+
# ... missing many others
256+
```
257+
258+
### Incremental Addition
259+
260+
If you encounter firewall denials, add ecosystems incrementally:
261+
262+
1. Start with `network: defaults`
263+
2. Add specific ecosystem: `network: { allowed: [defaults, python] }`
264+
3. Test and verify
265+
4. Add more ecosystems only as needed
266+
267+
## Troubleshooting Firewall Denials
268+
269+
### Identifying Blocked Domains
270+
271+
Use `gh aw logs` or `gh aw audit` to see firewall activity:
272+
273+
```bash
274+
gh aw logs --run-id <run-id>
275+
```
276+
277+
Look for denied requests in the firewall log section:
278+
279+
```
280+
🔥 Firewall Log Analysis
281+
Denied Domains:
282+
✗ registry.npmjs.org:443 (3 requests)
283+
✗ pypi.org:443 (2 requests)
284+
```
285+
286+
### Adding Missing Ecosystems
287+
288+
If you see denied domains for package registries:
289+
290+
1. **npm/Node.js domains** → Add `node` ecosystem
291+
2. **PyPI/Python domains** → Add `python` ecosystem
292+
3. **Docker/container domains** → Add `containers` ecosystem
293+
4. **Go module proxy** → Add `go` ecosystem
294+
295+
### Complete Example
296+
297+
Before (experiencing denials):
298+
```yaml
299+
network: defaults
300+
```
301+
302+
After (adding required ecosystems):
303+
```yaml
304+
network:
305+
allowed:
306+
- defaults
307+
- python # Fixed PyPI denials
308+
- node # Fixed npm denials
309+
- containers # Fixed Docker Hub denials
310+
```
311+
312+
## Common Patterns
313+
314+
### CI/CD Pipeline
315+
316+
```yaml
317+
network:
318+
allowed:
319+
- defaults
320+
- github # GitHub API
321+
- containers # Docker images
322+
- python # Python packages
323+
```
324+
325+
### Data Science Project
326+
327+
```yaml
328+
network:
329+
allowed:
330+
- defaults
331+
- python # PyPI, conda
332+
- github # GitHub datasets
333+
```
334+
335+
### Web Development
336+
337+
```yaml
338+
network:
339+
allowed:
340+
- defaults
341+
- node # npm packages
342+
- playwright # Browser testing
343+
- github # GitHub resources
344+
```
345+
346+
### DevOps Automation
347+
348+
```yaml
349+
network:
350+
allowed:
351+
- defaults
352+
- terraform # Infrastructure as code
353+
- containers # Container registries
354+
- github # GitHub API
355+
```
356+
357+
## No Network Access
358+
359+
For workflows that don't need external network access:
360+
361+
```yaml
362+
network: {}
363+
```
364+
365+
This denies all network access except what's required by the AI engine itself.
366+
367+
## Ecosystem Contents Reference
368+
369+
To see all domains in an ecosystem, check the [ecosystem domains source](https://github.com/githubnext/gh-aw/blob/main/pkg/workflow/data/ecosystem_domains.json).
370+
371+
### Quick Reference
372+
373+
| Ecosystem | Primary Domains | Purpose |
374+
|-----------|----------------|---------|
375+
| `defaults` | certificates, JSON schema, Ubuntu mirrors | Basic infrastructure |
376+
| `python` | pypi.org, files.pythonhosted.org | Python packages |
377+
| `node` | registry.npmjs.org, yarnpkg.com | Node.js packages |
378+
| `go` | proxy.golang.org, sum.golang.org | Go modules |
379+
| `containers` | registry.hub.docker.com, ghcr.io | Container images |
380+
| `java` | repo.maven.apache.org, gradle.org | Java dependencies |
381+
| `dotnet` | nuget.org, dotnet.microsoft.com | .NET packages |
382+
| `ruby` | rubygems.org | Ruby gems |
383+
| `rust` | crates.io | Rust crates |
384+
| `github` | githubusercontent.com, github.com | GitHub resources |
385+
386+
## Related Documentation
387+
388+
- [Network Permissions Reference](/gh-aw/reference/network/) - Complete network configuration reference
389+
- [Security Guide](/gh-aw/guides/security/) - Security best practices
390+
- [Troubleshooting](/gh-aw/troubleshooting/common-issues/) - Common issues and solutions

0 commit comments

Comments
 (0)