[software-development-practices:github-well-architected] github/gh-aw-firewall repository guidance

Advisory only: this review is non-binding and does not prove security, compliance, certification, endorsement, or complete alignment. It is a repository-observable snapshot that requires human review.

Target repository: `github/gh-aw-firewall`
Analyzed target commit: `dc72343e8b537413324cc6ed119576bedbb05f99`
Source verification date: `2026-09-03`
Well-Architected source revision: `16a9003d5c8e5a8f310d8f590ac6b6e0695e3f15`
Official URLs:
- https://learn.github.com/well-architected/
- https://wellarchitected.github.com/
- https://github.com/github/github-well-architected
- https://docs.github.com/

`assessment_marker: software-development-practices/github-well-architected target=github/gh-aw-firewall commit=dc72343e8b537413324cc6ed119576bedbb05f99 source_rev=16a9003d5c8e5a8f310d8f590ac6b6e0695e3f15`

## Scope, assumptions, inaccessible evidence, and limitations
- Assessed only the checked-out `target/` snapshot and bounded GitHub metadata for `github/gh-aw-firewall`.
- Pillar baseline verified against the current official framework: Productivity, Collaboration, Application Security, Governance, and Architecture.
- GitHub Docs was treated as the implementation source of truth only for feature interpretation and prerequisites.
- Branch protection details, security settings, secret scanning, code scanning alerts, rulesets, environments, and some Actions/repository policy endpoints were not readable with the available token and are marked `NOT_ASSESSED` or `HUMAN_REVIEW_REQUIRED` where relevant.
- Repository evidence cannot prove organization-wide governance, access-review, incident-response, or enterprise policy practice.
- An existing tracked issue with the required current source revision and target commit was not found in `githubnext/gh-aw-cao`.

## Pillar-to-evidence matrix

| Pillar | Status | Official page / principle | Repository evidence | Limitations / assumptions | Concrete improvement |
|---|---|---|---|---|---|
| Productivity | OBSERVED | Well-Architected Productivity guidance on reliable developer workflows and automation | Multiple CI workflows exist for build, lint, type-check, coverage, supply-chain scanning, and docs deploy: `.github/workflows/build.yml`, `lint.yml`, `test-integration.yml`, `test-coverage.yml`, `supply-chain-scan.yml`. `package.json` exposes build/test/lint scripts for local parity. | Does not prove workflow reliability targets or lead-time metrics. | Preserve local/CI parity and pinned actions as the repo scales. |
| Collaboration | PARTIAL | Well-Architected Collaboration guidance on shared ownership and contribution flow | `CODEOWNERS` is present and routes all changes plus sensitive paths to a maintainer; `CONTRIBUTING.md` and `CODE_OF_CONDUCT.md` exist; `ci-gate.yml` guides contributors before expensive agentic CI. | Single visible default owner in `CODEOWNERS` may create review concentration risk; cannot verify team review load or branch-review enforcement. | Expand sensitive path ownership to a team alias or backup maintainers to reduce bottlenecks and review single points of failure. |
| Application Security | PARTIAL | Well-Architected Application Security guidance on enabling platform security capabilities and dependency hygiene | `codeql.yml` runs CodeQL on push, PR, and schedule; `dependency-audit.yml` runs `npm audit` and uploads SARIF; `supply-chain-scan.yml` builds/scans first-party container images and scans published images with pinned scanner digests; release workflow signs images and attests SBOMs with cosign. | Cannot verify Advanced Security enablement, alert triage, secret scanning, or protection/ruleset enforcement from available access. | Add GitHub dependency review on pull requests so dependency-risk diffs are surfaced before merge. |
| Governance | HUMAN_REVIEW_REQUIRED | Well-Architected Governance guidance on policy enforcement and controlled change management | Workflows use pinned SHAs for several third-party actions; release workflow verifies release branch shape and uses explicit permissions; repository metadata shows default branch `main`. | Branch protection/rulesets/workflow permission defaults returned `Resource not accessible by integration`; org/repo policy posture cannot be concluded. | Human review branch protections, rulesets, and least-privilege workflow defaults against repository risk. |
| Architecture | OBSERVED | Well-Architected Architecture guidance on maintainable system structure and documented constraints | README and docs describe runtime topology, security model, compatibility, config schema, and architecture. Source layout separates runtime, services, parsers, microvm, and docs. | Documentation accuracy was sampled, not exhaustively validated. | Preserve architecture docs and schema-driven configuration as features expand. |

## Prioritized improvement backlog

1. **Add a dedicated GitHub Dependency Review pull-request workflow**
- **Priority:** P1
- **Status basis:** `GAP_FOUND`
- **Official rationale:** GitHub Well-Architected Application Security emphasizes shift-left repository security controls that help maintainers review dependency changes before merge; GitHub Docs identifies dependency review as the built-in pull-request feature for surfacing risky dependency diffs.
- **Evidence:** The repository has strong post-change and scheduled controls (`.github/workflows/dependency-audit.yml`, `.github/workflows/supply-chain-scan.yml`, `.github/workflows/codeql.yml`) and Dependabot configuration in `.github/dependabot.yml`, but no `.github/workflows/dependency-review.yml` or equivalent workflow was present in the target snapshot or the repository contents listing.
- **Owner surface:** Repository maintainers.
- **Dependencies / prerequisites:** GitHub dependency graph support; if GitHub Advanced Security features are limited for some contexts, the fallback is to keep Dependabot plus audit/supply-chain scans, but dependency review remains the proportionate PR-time control when available.
- **Expected maintainer benefit:** Earlier, lower-noise detection of newly introduced vulnerable or high-risk dependency changes in pull requests, reducing reviewer burden and time-to-remediation before merge.
- **Acceptance checks:**
- A PR-triggered workflow using `actions/dependency-review-action` (or current official equivalent) exists.
- The workflow scopes permissions minimally, typically `contents: read`.
- The workflow blocks or clearly flags unacceptable severity/license policy outcomes on PRs.
- Maintainers document exceptions or fallback behavior for unsupported ecosystems.

Why this was prioritized over other observations

- It is repository-owned and directly actionable without requiring org-admin access.
- The repo already demonstrates strong security intent; this closes a clear PR-time gap between dependency update generation and after-the-fact audit/scan workflows.
- Other notable topics, such as branch protection, rulesets, secret scanning, and enterprise governance, were not fully observable and therefore were not promoted as evidence-backed backlog items here.

## Strengths worth preserving
- Broad CI coverage across build, lint, type-check, integration, coverage, and supply-chain workflows.
- Security-conscious release process with explicit permissions, cosign signing, and SBOM attestation.
- Dependabot coverage across npm, Docker, docs-site, and GitHub Actions ecosystems.
- Clear architecture and security documentation supporting contributor understanding.
- CODEOWNERS coverage for sensitive paths.

## Human-review questions
- Are default-branch protections/rulesets enforcing required reviews, required status checks, and restricted release changes as intended?
- Are secret scanning, Dependabot alerts, and CodeQL alerts enabled and triaged with documented ownership?
- Should `CODEOWNERS` include a team alias or backup owners for `/containers/`, `/src/`, and workflow paths to reduce review bottlenecks?
- Are workflow permission defaults set to least privilege repository-wide, especially for comment-writing and PR-writing workflows?

### Control Plane
- Correlation ID: `33817398919-18`
- Central repository: `githubnext/gh-aw-cao`
- Control plane run URL: https://github.com/githubnext/gh-aw-cao/actions/runs/33817398919

> Generated by [:mark-github: Dev Practices / Well-Architected](https://github.com/githubnext/gh-aw-cao/actions/runs/33817744721) · pi · gpt54 · 30.6 AIC · ⌖ 8.51 AIC · ⊞ 8.5K · [◷](https://github.com/search?q=repo%3Agithubnext%2Fgh-aw-cao+is%3Aissue+%22gh-aw-workflow-call-id%3A+githubnext%2Fgh-aw-cao%2Fsoftware-development-practices-github-well-architected%22&type=issues)
> - [x] expires on Oct 3, 2026, 11:33 PM UTC

Start with .github/workflows/dependency-audit.yml, .github/workflows/supply-chain-scan.yml, .github/workflows/codeql.yml, and .github/dependabot.yml to match existing conventions. Add the PR-time dependency review workflow using the official action, minimal permissions, and documented fallback behavior. Done means pull requests surface or block unacceptable dependency-risk outcomes without requiring broader repository policy changes.

Written by the indexing model from the issue text.