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

Advisory review: `github/gh-aw-mcpg` already shows strong workflow automation and security-conscious release hygiene, but the repository snapshot does not show any repository-visible CODEOWNERS policy. Adding a root `CODEOWNERS` file is the highest-confidence GitHub Well-Architected improvement because it directly strengthens review routing, shared ownership, and governance for this workflow-heavy repository with low implementation effort.

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

> [!IMPORTANT]
> This issue is advisory and non-binding. It does **not** prove security, compliance, certification, endorsement, or complete alignment with GitHub Well-Architected guidance. Repository-level evidence is incomplete for organization and enterprise controls, so human review is still required.

## Repository and source metadata
- Target repository: `github/gh-aw-mcpg`
- Analyzed target commit: `97a3970b35f6c076d596c650e462755b0b48215f`
- Source verification date: `2026-09-03`
- GitHub Well-Architected source revision: `16a9003d5c8e5a8f310d8f590ac6b6e0695e3f15`
- Official URLs verified:
- https://learn.github.com/well-architected/
- https://github.com/github/github-well-architected
- https://raw.githubusercontent.com/github/github-well-architected/main/README.md
- https://raw.githubusercontent.com/github/github-well-architected/main/docs/framework-overview.md
- https://docs.github.com/

## Scope, assumptions, inaccessible evidence, and limitations
- Scope is limited to the checked-out `target/` repository snapshot plus bounded public GitHub repository metadata.
- The current official framework baseline still presents five pillars: Productivity, Collaboration, Application Security, Governance, and Architecture.
- GitHub Docs was treated as implementation source of truth only for feature availability and prerequisites.
- Organization and enterprise controls cannot be established from repository evidence alone and are marked `HUMAN_REVIEW_REQUIRED` or `NOT_ASSESSED`.
- Branch protection, code scanning alerts, Dependabot alert state, secret scanning, rulesets, and other admin-only repository settings were not readable with the available credential and are therefore not treated as gaps unless repository evidence showed contradiction.
- A prior open review issue with the exact tracked title was not found in `githubnext/gh-aw-cao`.
- No open `[software-development-practices:nist-ssdf]` issue for this target was available in current worker scope, so no cross-worker deduplication could be confirmed.

## Pillar-to-evidence matrix

| Pillar | Status | Official page / principle | Repository evidence | Evidence limits / assumptions | Concrete improvement |
| --- | --- | --- | --- | --- | --- |
| Productivity | OBSERVED | GitHub Well-Architected Framework Overview → Productivity pillar | `.github/workflows/ci.yml` runs unit, lint, integration, and race testing; repository includes many automation workflows under `.github/workflows/`; README documents local setup and testing commands. | Repository evidence shows automation presence, not actual adoption quality over time. | Preserve the current CI/test automation breadth and keep action pinning discipline as workflows evolve. |
| Collaboration | GAP_FOUND | GitHub Well-Architected Framework Overview → Collaboration pillar | Repository has issues enabled and extensive workflow-based collaboration patterns, but no repository-visible `CODEOWNERS` file was found in the target snapshot root or `.github/`. | Repository may use informal reviewer norms, but no machine-enforced ownership routing was visible. | Add a root `CODEOWNERS` file covering workflows, docs, security-sensitive paths, and runtime code. |
| Application Security | PARTIAL | GitHub Well-Architected Framework Overview → Application Security pillar | `SECURITY.md` provides a disclosure path; `release.md` includes release-time test reruns, cache disabling for release security, SBOM generation, and artifact auditing; workflow actions in `ci.yml` and `container.yml` are SHA pinned. | Alerting/configuration state for code scanning, Dependabot, and secret scanning was unreadable with current token. | Document and surface repository-visible ownership for sensitive paths so security reviews route predictably. |
| Governance | PARTIAL | GitHub Well-Architected Framework Overview → Governance pillar | Workflows declare least-privilege permissions per job in multiple files; repository contains dedicated agent/workflow guidance and structured automation conventions. | Branch protections, rulesets, environment protection, and access policies were not readable. | Add CODEOWNERS to complement permissions with explicit ownership boundaries and review expectations. |
| Architecture | OBSERVED | GitHub Well-Architected Framework Overview → Architecture pillar | README and docs describe routed/unified modes, guards, auth, tracing, and configuration patterns; repository structure cleanly separates docs, internal code, guards, workflows, and containers. | Repository evidence shows intended architecture, not production deployment quality. | Preserve the current documentation depth and path separation for gateway, guards, and workflow assets. |

## Prioritized improvement backlog

1. **Add a repository `CODEOWNERS` file**
- **Priority:** P1
- **Status:** Untracked recommendation
- **Official alignment:** Collaboration and Governance pillars
- **Evidence:** No `CODEOWNERS` file was visible in the repository snapshot while the repo contains many sensitive automation assets under `.github/workflows/`, `.github/agentics/`, `guards/`, `internal/`, and release workflows.
- **Rationale / maintainer benefit:** Ensures reviews are automatically requested from the right maintainers, reduces ambiguous ownership for workflow and security-sensitive changes, improves continuity during contributor growth, and makes governance more durable than convention alone.
- **Owner surface:** Repository-owned
- **Dependencies / prerequisites:** None; optional follow-on alignment with branch protection if maintainers want required reviews enforced.
- **Proportionate implementation suggestion:**
- Create `CODEOWNERS` at repo root.
- Cover at least:
- `/.github/workflows/` and `/.github/agentics/`
- `/guards/`
- `/internal/`
- `/docs/`
- `/Dockerfile`, `/containers/`, and release-related assets
- Keep ownership groups broad enough to avoid review bottlenecks.
- **Acceptance checks:**
- [ ] `CODEOWNERS` exists at repository root or `.github/CODEOWNERS`
- [ ] Workflow, security-sensitive, docs, and runtime code paths have explicit owners
- [ ] Maintainers verify owners map to currently active teams or individuals
- [ ] Maintainers decide whether branch/ruleset review enforcement should require CODEOWNERS approval

## Strengths worth preserving
- CI coverage is broad and separated by concern across unit, lint, integration, and race testing.
- Actions are pinned by commit SHA in key workflows, which is a strong repository-visible supply-chain hygiene practice.
- Release automation shows deliberate security choices such as retesting, cache disabling for release builds, and SBOM generation.
- Repository documentation is unusually thorough for gateway architecture, configuration, and operator guidance.

## Human-review questions
- Are branch protections or rulesets already enforcing required reviews, status checks, and signed/linear history on `main`?
- Are CodeQL, secret scanning, Dependabot alerts, and Dependabot security updates enabled at the repository or organization level?
- Which maintainers or teams should own workflow, guard, runtime, and documentation paths without creating approval bottlenecks?
- Are there organization-level governance requirements for Actions usage, environment protection, or package publishing that should be reflected in repository-visible policy files?

> Generated by [:mark-github: Dev Practices / Well-Architected](https://github.com/githubnext/gh-aw-cao/actions/runs/33817758844) · pi · gpt54 · 23.5 AIC · ⌖ 8.49 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:36 PM UTC

Start by reviewing the repository paths named in the issue, especially .github/workflows/, .github/agentics/, guards/, internal/, docs/, Dockerfile, and containers/. Create a root CODEOWNERS file with owners verified by maintainers for workflow, security-sensitive, runtime, documentation, and release paths. Done means the file exists, all listed areas have explicit active owners, and maintainers confirm whether review enforcement should follow.

Written by the indexing model from the issue text.