feat: add AWF JSON/YAML config ingestion with schema validation and CLI precedence by Copilot · Pull Request #2018 · github/gh-aw-firewall

Copilot · 2026-04-16T04:34:00Z

AWF’s growing flag surface made non-trivial invocations hard to maintain and share. This change introduces JSON/YAML config-file support (including stdin), validates config shape early, and formalizes a tooling-oriented configuration contract that gh-aw can consume.

CLI config ingestion + precedence
- Added --config <path|-> to load config from JSON/YAML files or stdin (--config -).
- Mapped structured config fields onto existing CLI option semantics.
- Enforced precedence: explicit CLI flags override config values.
Structured config parsing/validation
- Added src/config-file.ts for:
  - parse flow (JSON, YAML, extensionless fallback),
  - validation with clear path-scoped errors,
  - option mapping and in-place merge with CLI source-awareness.
- Kept behavior aligned with existing CLI capabilities (including negated flags like --no-rate-limit).
Schema + W3C-style spec for compiler/tooling
- Added docs/awf-config.schema.json (machine-readable schema for IDE/completion/validation).
- Added docs/awf-config-spec.md (normative processing model, conformance, precedence, and CLI mapping) to serve as the contract for gh-aw compiler integration.
Coverage and docs updates
- Added src/config-file.test.ts for parsing, validation, stdin mode, mapping, and precedence behavior.
- Linked schema/spec from README for discoverability.

Example config usage:

# file-based
awf --config awf.yaml -- claude --prompt "do the thing"

# stdin-based
cat awf.json | awf --config - -- claude --prompt "do the thing"

Example schema-backed config shape:

{
  "$schema": "https://raw.githubusercontent.com/github/gh-aw-firewall/main/docs/awf-config.schema.json",
  "network": {
    "allowDomains": ["github.com", "api.github.com"],
    "dnsServers": ["1.1.1.1", "1.0.0.1"]
  },
  "apiProxy": {
    "enabled": true,
    "targets": {
      "openai": { "host": "api.openai.com", "basePath": "/v1" }
    }
  },
  "logging": {
    "logLevel": "debug"
  }
}

Agent-Logs-Url: https://github.com/github/gh-aw-firewall/sessions/dcd77d8b-19a4-4eab-9b64-5772d37fda34

Copilot

Pull request overview

Adds first-class AWF config-file support (JSON/YAML, including stdin) with early shape validation, a deterministic precedence model (CLI overrides config), and a formal config contract for tooling.

Changes:

Introduces --config <path|-> to load JSON/YAML config files (or stdin via -) and merge into Commander options with CLI precedence.
Adds runtime config parsing + validation + CLI option mapping (src/config-file.ts) and corresponding Jest coverage.
Publishes a JSON Schema + normative spec documenting the config model and CLI mapping, and links them from the README.

Show a summary per file

File	Description
src/config-file.ts	Implements config parsing (JSON/YAML/stdin), validation, mapping to existing CLI option names, and CLI-precedence merge.
src/config-file.test.ts	Adds unit tests for validation, parsing (file/stdin), mapping, and precedence behavior.
src/cli.ts	Wires `--config` into the CLI and applies config-derived options before existing option validation/processing.
docs/awf-config.schema.json	Defines the machine-readable schema for config files (closed-world / `additionalProperties: false`).
docs/awf-config-spec.md	Documents the normative processing model, precedence rules, and CLI mapping contract for tooling.
README.md	Links the new schema and spec for discoverability.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files reviewed: 6/6 changed files
Comments generated: 0

github-actions · 2026-04-16T15:02:47Z

Documentation Preview

Documentation build failed for this PR. View logs.

Built from commit 306cd97

github-actions · 2026-04-16T15:02:52Z

⚠️ Coverage Regression Detected

This PR decreases test coverage. Please add tests to maintain coverage levels.

Overall Coverage

Metric	Base	PR	Delta
Lines	85.35%	84.41%	📉 -0.94%
Statements	85.24%	83.64%	📉 -1.60%
Functions	87.96%	87.39%	📉 -0.57%
Branches	77.95%	74.82%	📉 -3.13%

📁 Per-file Coverage Changes (2 files)

File	Lines (Before → After)	Statements (Before → After)
`src/cli.ts`	59.5% → 58.9% (-0.61%)	60.0% → 59.4% (-0.61%)
`src/docker-manager.ts`	86.8% → 87.1% (+0.30%)	86.4% → 86.7% (+0.29%)

✨ New Files (1 files)

src/config-file.ts: 65.6% lines

Coverage comparison generated by scripts/ci/compare-coverage.ts

…o local variable' Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

github-actions · 2026-04-16T15:19:01Z

⚠️ Coverage Regression Detected

This PR decreases test coverage. Please add tests to maintain coverage levels.

Overall Coverage

Metric	Base	PR	Delta
Lines	85.35%	84.41%	📉 -0.94%
Statements	85.24%	83.64%	📉 -1.60%
Functions	87.96%	87.39%	📉 -0.57%
Branches	77.95%	74.82%	📉 -3.13%

📁 Per-file Coverage Changes (2 files)

File	Lines (Before → After)	Statements (Before → After)
`src/cli.ts`	59.5% → 58.9% (-0.61%)	60.0% → 59.4% (-0.61%)
`src/docker-manager.ts`	86.8% → 87.1% (+0.30%)	86.4% → 86.7% (+0.29%)

✨ New Files (1 files)

src/config-file.ts: 65.3% lines

Coverage comparison generated by scripts/ci/compare-coverage.ts

The initial apt-get update can fail with hash mismatches when Ubuntu mirrors are mid-sync. The existing retry logic only covered apt-get install failures, not apt-get update failures. This adds a retry with cache clear for the initial apt-get update in both agent and squid Dockerfiles. Fixes: squid-proxy build failure (exit code 100) in --build-local CI Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions · 2026-04-16T15:27:50Z

⚠️ Coverage Regression Detected

This PR decreases test coverage. Please add tests to maintain coverage levels.

Overall Coverage

Metric	Base	PR	Delta
Lines	85.35%	84.41%	📉 -0.94%
Statements	85.24%	83.64%	📉 -1.60%
Functions	87.96%	87.39%	📉 -0.57%
Branches	77.95%	74.82%	📉 -3.13%

📁 Per-file Coverage Changes (2 files)

File	Lines (Before → After)	Statements (Before → After)
`src/cli.ts`	59.5% → 58.9% (-0.61%)	60.0% → 59.4% (-0.61%)
`src/docker-manager.ts`	86.8% → 87.1% (+0.30%)	86.4% → 86.7% (+0.29%)

✨ New Files (1 files)

src/config-file.ts: 65.3% lines

Coverage comparison generated by scripts/ci/compare-coverage.ts

The byok-copilot feature flag generates an empty COPILOT_MODEL fallback, but BYOK providers require an explicit model. This patches the lock file with claude-sonnet-4.5 as the default. Workaround for: github/gh-aw#26565 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions · 2026-04-16T15:37:47Z

⚠️ Coverage Regression Detected

This PR decreases test coverage. Please add tests to maintain coverage levels.

Overall Coverage

Metric	Base	PR	Delta
Lines	85.35%	84.41%	📉 -0.94%
Statements	85.24%	83.64%	📉 -1.60%
Functions	87.96%	87.39%	📉 -0.57%
Branches	77.95%	74.82%	📉 -3.13%

📁 Per-file Coverage Changes (2 files)

File	Lines (Before → After)	Statements (Before → After)
`src/cli.ts`	59.5% → 58.9% (-0.61%)	60.0% → 59.4% (-0.61%)
`src/docker-manager.ts`	86.8% → 87.1% (+0.30%)	86.4% → 86.7% (+0.29%)

✨ New Files (1 files)

src/config-file.ts: 65.3% lines

Coverage comparison generated by scripts/ci/compare-coverage.ts

Replace single-retry apt-get update with a 3-attempt retry loop using exponential backoff (10s, 20s, 30s). The single retry was insufficient when Ubuntu mirrors are in prolonged sync states (observed in CI where mirror hash mismatches persisted across multiple minutes). The apt_update_retry function clears the apt cache before each attempt, ensuring a clean state. Applied to all apt-get update calls in both agent and squid Dockerfiles, including the install-retry fallback paths. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions · 2026-04-16T17:20:29Z

⚠️ Coverage Regression Detected

This PR decreases test coverage. Please add tests to maintain coverage levels.

Overall Coverage

Metric	Base	PR	Delta
Lines	85.35%	84.41%	📉 -0.94%
Statements	85.24%	83.64%	📉 -1.60%
Functions	87.96%	87.39%	📉 -0.57%
Branches	77.95%	74.82%	📉 -3.13%

📁 Per-file Coverage Changes (2 files)

File	Lines (Before → After)	Statements (Before → After)
`src/cli.ts`	59.5% → 58.9% (-0.61%)	60.0% → 59.4% (-0.61%)
`src/docker-manager.ts`	86.8% → 87.1% (+0.30%)	86.4% → 86.7% (+0.29%)

✨ New Files (1 files)

src/config-file.ts: 65.3% lines

Coverage comparison generated by scripts/ci/compare-coverage.ts

GitHub Actions runners are Azure-hosted, so azure.archive.ubuntu.com is geographically closer and more reliable than archive.ubuntu.com. This reduces Hash Sum mismatch failures during Ubuntu mirror syncs. Handles both traditional sources.list (jammy/22.04) and DEB822 format (noble/24.04+) used by ubuntu/squid:latest. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions · 2026-04-16T17:34:23Z

⚠️ Coverage Regression Detected

This PR decreases test coverage. Please add tests to maintain coverage levels.

Overall Coverage

Metric	Base	PR	Delta
Lines	85.35%	84.41%	📉 -0.94%
Statements	85.24%	83.64%	📉 -1.60%
Functions	87.96%	87.39%	📉 -0.57%
Branches	77.95%	74.82%	📉 -3.13%

📁 Per-file Coverage Changes (2 files)

File	Lines (Before → After)	Statements (Before → After)
`src/cli.ts`	59.5% → 58.9% (-0.61%)	60.0% → 59.4% (-0.61%)
`src/docker-manager.ts`	86.8% → 87.1% (+0.30%)	86.4% → 86.7% (+0.29%)

✨ New Files (1 files)

src/config-file.ts: 65.3% lines

Coverage comparison generated by scripts/ci/compare-coverage.ts

github-actions · 2026-04-16T17:36:38Z

Smoke Test Results

✅ GitHub MCP: chore: recompile workflows for gh-aw v0.68.5 / chore: upgrade gh-aw to v0.68.4 and recompile workflows
✅ Playwright: github.com title contains "GitHub"
✅ File Write: /tmp/gh-aw/agent/smoke-test-claude-24524657144.txt created
✅ Bash: File verified via cat

Overall: PASS

💥 [THE END] — Illustrated by Smoke Claude

github-actions · 2026-04-16T17:36:51Z

Copilot Smoke Test Results ✅

GitHub MCP: ✅ Listed PR #2006 by @lpcox
GitHub.com: ✅ HTTP 200
File I/O: ✅ /tmp/gh-aw/agent/smoke-test-copilot-24524657075.txt

Status: PASS

cc @lpcox @Copilot

📰 BREAKING: Report filed by Smoke Copilot

github-actions · 2026-04-16T17:37:18Z

Smoke Test: GitHub Actions Services Connectivity

Check	Result
Redis `PING` (`host.docker.internal:6379`)	✅ `PONG` (via `nc` — `redis-cli` unavailable, no root)
PostgreSQL `pg_isready` (`host.docker.internal:5432`)	✅ accepting connections
PostgreSQL `SELECT 1` (`smoketest` db, user `postgres`)	✅ returned `1`

All checks passed.

🔌 Service connectivity validated by Smoke Services

github-actions · 2026-04-16T17:38:06Z

🤖 OpenCode Smoke Test Results

✅ GitHub MCP: Read last 2 merged PRs (fix: add explicit model for Copilot BYOK smoke test, feat: add smoke test for Copilot CLI offline BYOK mode)
✅ File Writing: /tmp/gh-aw/agent/smoke-test-opencode-24524657146.txt created and verified
✅ Bash Tool: File read back successfully
✅ Build AWF: npm ci && npm run build succeeded

Overall: PASS

🌐 Transmitted by Smoke OpenCode

github-actions · 2026-04-16T17:38:07Z

Smoke Test Status

PR: fix: add explicit model for Copilot BYOK smoke test
PR: feat: add smoke test for Copilot CLI offline BYOK mode
GitHub MCP (last 2 merged PRs): ✅
Safe Inputs GH CLI (safeinputs-gh): ❌
Playwright title contains "GitHub": ✅
Tavily web search: ❌
File write + bash cat: ✅
Build (npm ci && npm run build): ✅
Discussion interaction (github-discussion-query + oracle comment): ❌
Overall status: FAIL

🔮 The oracle has spoken through Smoke Codex

github-actions · 2026-04-16T17:38:41Z

Chroot Version Comparison Results

Runtime	Host Version	Chroot Version	Match?
Python	Python 3.12.13	Python 3.12.3	❌ NO
Node.js	v24.14.1	v20.20.2	❌ NO
Go	go1.22.12	go1.22.12	✅ YES

Overall: ❌ Not all tests passed — Python and Node.js versions differ between host and chroot environments.

Tested by Smoke Chroot

github-actions · 2026-04-16T17:40:34Z

🏗️ Build Test Suite Results

Ecosystem	Project	Build/Install	Tests	Status
Bun	elysia	✅	1/1 passed	✅ PASS
Bun	hono	✅	1/1 passed	✅ PASS
C++	fmt	✅	N/A	✅ PASS
C++	json	✅	N/A	✅ PASS
Deno	oak	N/A	1/1 passed	✅ PASS
Deno	std	N/A	1/1 passed	✅ PASS
.NET	hello-world	✅	N/A	✅ PASS
.NET	json-parse	✅	N/A	✅ PASS
Go	color	✅	1/1 passed	✅ PASS
Go	env	✅	1/1 passed	✅ PASS
Go	uuid	✅	1/1 passed	✅ PASS
Java	gson	✅	1/1 passed	✅ PASS
Java	caffeine	✅	1/1 passed	✅ PASS
Node.js	clsx	✅	All passed	✅ PASS
Node.js	execa	✅	All passed	✅ PASS
Node.js	p-limit	✅	All passed	✅ PASS
Rust	fd	✅	1/1 passed	✅ PASS
Rust	zoxide	✅	1/1 passed	✅ PASS

Overall: 8/8 ecosystems passed — ✅ PASS

Notes: Java Maven required a writable local repository path (-Dmaven.repo.local=/tmp/gh-aw/agent/m2-repo) since the default ~/.m2/repository was owned by root in this environment. All builds and tests succeeded.

Generated by Build Test Suite for issue #2018 · ● 602.5K · ◷

Initial plan

e9575dc

Copilot AI assigned Copilot and lpcox Apr 16, 2026

Copilot started work on behalf of lpcox April 16, 2026 04:34 View session

Copilot AI linked an issue Apr 16, 2026 that may be closed by this pull request

feat: JSON/YAML config file as alternative to CLI flags #2017

Closed

Copilot AI added 4 commits April 16, 2026 04:40

feat: add JSON/YAML config file loading and schema docs

71c1438

Agent-Logs-Url: https://github.com/github/gh-aw-firewall/sessions/dcd77d8b-19a4-4eab-9b64-5772d37fda34

refactor: tighten config validation helpers and precedence docs

78a93ef

Agent-Logs-Url: https://github.com/github/gh-aw-firewall/sessions/dcd77d8b-19a4-4eab-9b64-5772d37fda34

docs: clarify config parsing and RFC wording

7b29d41

Agent-Logs-Url: https://github.com/github/gh-aw-firewall/sessions/dcd77d8b-19a4-4eab-9b64-5772d37fda34

refactor: clarify in-place config option merge behavior

e3164df

Agent-Logs-Url: https://github.com/github/gh-aw-firewall/sessions/dcd77d8b-19a4-4eab-9b64-5772d37fda34

Copilot AI changed the title ~~[WIP] Add JSON/YAML config file as alternative to CLI flags~~ Add AWF JSON/YAML config ingestion with schema validation, CLI precedence, and formal config spec Apr 16, 2026

Copilot finished work on behalf of lpcox April 16, 2026 04:47

Copilot AI requested a review from lpcox April 16, 2026 04:47

lpcox marked this pull request as ready for review April 16, 2026 14:26

lpcox requested a review from Mossaka as a code owner April 16, 2026 14:26

Copilot AI review requested due to automatic review settings April 16, 2026 14:26

Copilot started reviewing on behalf of lpcox April 16, 2026 14:26 View session

Copilot AI reviewed Apr 16, 2026

View reviewed changes

github-advanced-security AI found potential problems Apr 16, 2026

View reviewed changes

Comment thread src/config-file.ts Fixed

Potential fix for pull request finding 'CodeQL / Useless assignment t…

dd2d1c7

…o local variable' Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

github-actions bot added the build-test label Apr 16, 2026

This comment has been minimized.

Sign in to view

lpcox changed the title ~~Add AWF JSON/YAML config ingestion with schema validation, CLI precedence, and formal config spec~~ feat: add AWF JSON/YAML config ingestion with schema validation and CLI precedence Apr 16, 2026

github-actions bot added smoke-claude smoke-copilot labels Apr 16, 2026

github-actions bot mentioned this pull request Apr 16, 2026

[aw] No-Op Runs #1993

Closed

github-actions bot added the smoke-services label Apr 16, 2026

github-actions bot added the smoke-opencode label Apr 16, 2026

lpcox merged commit c923b80 into main Apr 16, 2026
62 of 65 checks passed

lpcox deleted the copilot/add-json-yaml-config-support branch April 16, 2026 17:56

lpcox mentioned this pull request Apr 16, 2026

feat: configure AWF via JSON/YAML config instead of CLI flags github/gh-aw#26700

Open

github-actions bot mentioned this pull request Apr 16, 2026

fix: make smoke-claude safe outputs trigger-aware for workflow_dispatch #2036

Merged

github-actions bot mentioned this pull request Apr 16, 2026

fix: allow package.json/lock in dep security monitor PRs #2041

Merged

Conversation

Copilot AI commented Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

github-actions bot commented Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation Preview

Uh oh!

github-actions bot commented Apr 16, 2026

⚠️ Coverage Regression Detected

Overall Coverage

Uh oh!

Uh oh!

github-actions bot commented Apr 16, 2026

⚠️ Coverage Regression Detected

Overall Coverage

Uh oh!

github-actions bot commented Apr 16, 2026

⚠️ Coverage Regression Detected

Overall Coverage

Uh oh!

github-actions bot commented Apr 16, 2026

⚠️ Coverage Regression Detected

Overall Coverage

Uh oh!

This comment has been minimized.

This comment has been minimized.

github-actions bot commented Apr 16, 2026

⚠️ Coverage Regression Detected

Overall Coverage

Uh oh!

github-actions bot commented Apr 16, 2026

⚠️ Coverage Regression Detected

Overall Coverage

Uh oh!

github-actions bot commented Apr 16, 2026

Smoke Test Results

Uh oh!

github-actions bot commented Apr 16, 2026

Copilot Smoke Test Results ✅

Uh oh!

github-actions bot commented Apr 16, 2026

Smoke Test: GitHub Actions Services Connectivity

Uh oh!

github-actions bot commented Apr 16, 2026

🤖 OpenCode Smoke Test Results

Uh oh!

github-actions bot commented Apr 16, 2026

Smoke Test Status

Uh oh!

github-actions bot commented Apr 16, 2026

Chroot Version Comparison Results

Uh oh!

github-actions bot commented Apr 16, 2026

🏗️ Build Test Suite Results

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Copilot AI commented Apr 16, 2026 •

edited

Loading

github-actions bot commented Apr 16, 2026 •

edited

Loading