github / github/gh-aw

feat: configure AWF via JSON/YAML config instead of CLI flags

Open
#26,700 0 comments 0 reactions 1 assignee Claimed by @lpcox View on GitHub
compiler enhancement workflows
Dominant language
Go
Stars
5.1k
Forks
541
Avg merge
5h 46m
Merged PRs (30d)
760

Description

## Summary

AWF now supports a formal JSON/YAML configuration model as an alternative to its 53+ CLI flags. The `gh-aw` compiler should adopt this config file to configure AWF, replacing the growing list of `--flag` arguments on the `awf` command line.

## Background

The AWF command line has become unwieldy — over 53 flags covering domains, DNS, proxy settings, container options, API proxy configuration, logging, and more. To address this, AWF now supports `--config ` which accepts a JSON or YAML configuration document.

The full specification and schema are published in the AWF repository:

- **W3C-style spec**: [`docs/awf-config-spec.md`](https://github.com/github/gh-aw-firewall/blob/main/docs/awf-config-spec.md)
- **JSON Schema**: [`docs/awf-config.schema.json`](https://github.com/github/gh-aw-firewall/blob/main/docs/awf-config.schema.json)
- **Implementation PR**: https://github.com/github/gh-aw-firewall/pull/2018
- **Original issue**: https://github.com/github/gh-aw-firewall/issues/2017

## Proposal

When `gh-aw` compiles a workflow lock file, it should:

1. **Generate an AWF config file** (JSON) containing all firewall settings (allowed domains, DNS servers, proxy config, logging options, container settings, etc.)
2. **Write the config to a temp file** in the workflow workspace (e.g., `/tmp/gh-aw/awf-config.json`)
3. **Invoke AWF with `--config`** instead of individual flags:
```bash
awf --config /tmp/gh-aw/awf-config.json --
```
instead of the current:
```bash
awf --allow-domains "dom1,dom2,..." --dns-servers "8.8.8.8" --log-level info --proxy-logs-dir ... --audit-dir ... --session-state-dir ... --enable-host-access --build-local --enable-api-proxy --difc-proxy-host ... --difc-proxy-ca-cert ... --
```

## Benefits

- **Readability**: Config is structured and self-documenting vs. a 500+ character command line
- **Validation**: JSON Schema provides static validation before AWF runs
- **Maintainability**: Adding new AWF options requires only schema + config changes, not flag parsing
- **Debuggability**: Config file can be inspected, diffed, and version-controlled
- **Processing model**: CLI flags still override config values, so per-invocation tweaks work

## Config Structure Example

```json
{
"allowDomains": ["github.com", "api.github.com", "registry.npmjs.org"],
"dnsServers": ["8.8.8.8", "8.8.4.4"],
"logLevel": "info",
"proxyLogsDir": "/tmp/gh-aw/sandbox/firewall/logs",
"auditDir": "/tmp/gh-aw/sandbox/firewall/audit",
"sessionStateDir": "/tmp/gh-aw/sandbox/agent/session-state",
"enableHostAccess": true,
"buildLocal": true,
"enableApiProxy": true,
"difcProxyHost": "host.docker.internal:18443",
"difcProxyCaCert": "/tmp/gh-aw/difc-proxy-tls/ca.crt",
"containerWorkdir": "/home/runner/work/repo/repo"
}
```

## Migration Path

This could be adopted incrementally:
1. Start by generating the config file alongside the existing flags
2. Validate that AWF produces identical behavior with `--config` vs. flags
3. Switch the compiled lock files to use `--config`
4. Eventually deprecate the long flag invocations in lock files

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.