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

Advisory only: this repository-observable review is non-binding guidance and does not prove security, compliance, certification, endorsement, or complete alignment with GitHub Well-Architected.

`github/gh-aw` has several strong repository-level practices in place already, including weekly Dependabot coverage across major ecosystems, committed CodeQL and additional scheduled security scanning workflows, and published contributor/security guidance. The highest-confidence repository-owned improvement still untracked from the evidence reviewed is to add a CODEOWNERS file so code review ownership is explicit and enforceable where branch protections or rulesets use it.

## Repository and source metadata
- Target repository: `github/gh-aw`
- Target commit: `e28ea11d1c27f1766931608814dc3801bd0b221f`
- Source verification date: 2026-09-03
- GitHub Well-Architected source revision: `16a9003d5c8e5a8f310d8f590ac6b6e0695e3f15`
- Official URLs consulted:
- `https://learn.github.com/well-architected/`
- `https://wellarchitected.github.com/`
- `https://github.com/github/github-well-architected`
- `https://docs.github.com/`

## Scope, assumptions, inaccessible evidence, and limitations
- Scope is limited to repository-observable evidence from the checked-out `target/` snapshot plus bounded GitHub metadata reads for `github/gh-aw`.
- The current framework baseline verified for this run remained: Productivity, Collaboration, Application Security, Governance, and Architecture.
- `https://learn.github.com/well-architected/` currently resolves to a generic GitHub Learn landing page rather than a directly inspectable framework page, so canonical framework structure was verified against `https://wellarchitected.github.com/` and the official `github/github-well-architected` source repository.
- Several governance and security control surfaces were inaccessible to this token via GitHub API (`403 Resource not accessible by integration`), including branch protection, Actions repository permissions, vulnerability-alert status, and code scanning alerts. Those topics are marked `HUMAN_REVIEW_REQUIRED`, `NOT_ASSESSED`, or `INCOMPLETE` instead of inferred.
- Repository-level evidence cannot establish enterprise or organization-wide practice; those questions remain for human review.
- An open tracking issue with the exact worker search title was not found in `githubnext/gh-aw-cao` during bounded search.

## Pillar-to-evidence matrix

| Pillar | Status | Official page / principle | Repository or metadata evidence | Evidence limits / assumptions | Concrete improvement |
|---|---|---|---|---|---|
| Productivity | OBSERVED | GitHub Well-Architected Productivity pillar; reduce friction with automation and maintainable workflows | `README.md`, `CONTRIBUTING.md`, and numerous committed CI workflows under `.github/workflows/` show documented local setup, build/test expectations, and broad automation coverage including `ci.yml` and focused integration jobs. | Could not assess actual queue times, flaky rates, or developer satisfaction from repository evidence alone. | Preserve the current documented dev-container and automation-first contributor workflow. |
| Collaboration | PARTIAL | GitHub Well-Architected Collaboration pillar; make ownership, contribution paths, and review flows clear | `CODE_OF_CONDUCT.md`, `CONTRIBUTING.md`, and `SECURITY.md` clearly define contributor behavior, security reporting, and the project’s contribution model. No `.github/CODEOWNERS` file was present in the repository snapshot or repository contents API. | Branch protections/rulesets that might compensate were not readable, so absence is limited to repository-visible ownership declaration. | Add `.github/CODEOWNERS` or repository-root `CODEOWNERS` covering critical paths. |
| Application Security | OBSERVED | GitHub Well-Architected Application Security pillar; use platform-native scanning and dependency hygiene | `.github/dependabot.yml` schedules weekly dependency updates across `gomod`, `npm`, `pip`, and `docker`; `.github/workflows/codeql.yml` runs scheduled CodeQL for `go`, `javascript`, and `actions`; `.github/workflows/security-scan.yml` adds scheduled `gosec` and `govulncheck`; `SECURITY.md` documents private vulnerability reporting. | Could not verify alert enforcement, secret scanning, or Dependabot/repository security settings due API limits. | Preserve scheduled security scanning and keep the documented private reporting path current. |
| Governance | HUMAN_REVIEW_REQUIRED | GitHub Well-Architected Governance pillar; apply policy, permissions, and guardrails consistently | Repository contains security-oriented workflow linting/configuration such as `.github/actionlint.yaml` and `.github/zizmor.yml`. | Could not read branch protection, rulesets, required reviews, Actions permissions, or org policy configuration; repository files alone are insufficient. | Human reviewers should confirm rulesets, review requirements, Actions restrictions, and default token permissions align with current governance policy. |
| Architecture | OBSERVED | GitHub Well-Architected Architecture pillar; structure repositories and automation for clear boundaries and evolution | `README.md` explains the repository’s purpose, generated workflow model, and supporting projects; `CONTRIBUTING.md` documents major directories and implementation patterns; workflow inventory shows decomposition into many focused workflows and support files. | Architectural fitness, coupling, and long-term operability beyond repository structure need maintainer review. | Preserve the explicit documentation of repository structure and separation of reusable workflow concerns. |

## Prioritized improvement backlog

### 1. Add a CODEOWNERS file for critical repository paths
- **Priority:** High
- **Status:** Untracked recommendation
- **Owner surface:** Repository maintainers
- **Pillar:** Collaboration, with secondary governance benefits
- **Evidence:** No `.github/CODEOWNERS` file was found via repository contents API, and no repository-root `CODEOWNERS` file was present in the reviewed snapshot. The repository has many sensitive paths, including `.github/workflows/`, `actions/`, `pkg/`, and documentation that shape user guidance and automation behavior.
- **Rationale / maintainer benefit:** A CODEOWNERS file makes review ownership explicit, reduces ambiguity for contributors, and lets maintainers pair repository knowledge with branch protection or ruleset enforcement where enabled. In a repository centered on workflow and security-sensitive automation, explicit ownership improves review consistency and maintainability.
- **Dependencies / prerequisites:** None for publishing the file. Additional benefit depends on maintainers verifying branch protection or rulesets are configured to request or require code-owner review.
- **Suggested scope:** Start with high-impact paths such as `.github/workflows/`, `actions/`, `pkg/`, `docs/`, and security/governance files; expand over time as ownership stabilizes.
- **Acceptance checks:**
- A `CODEOWNERS` file exists at a supported location.
- Critical paths have explicit owners.
- Human review confirms repository rules or branch protections use code-owner review where appropriate.

## Strengths worth preserving
- Weekly Dependabot coverage spans multiple ecosystems, including Docker, Go, npm, and pip.
- Scheduled CodeQL plus additional `gosec` and `govulncheck` workflows show layered repository-visible security automation.
- `SECURITY.md`, `CODE_OF_CONDUCT.md`, and `CONTRIBUTING.md` provide clear public guidance for contributors and reporters.
- The repository documents architecture, contributor workflow, and automation boundaries in detail, supporting maintainability.

## Human-review questions
- Are branch protections or repository rulesets configured to require reviews, restrict direct pushes, and request/require code-owner review on critical paths?
- Are Dependabot alerts, security updates, secret scanning, and push protection enabled for this repository at the appropriate level?
- Are GitHub Actions permissions restricted to approved actions or trusted sources where the current maintenance model allows it?
- Should any critical workflow or package paths have distinct owners to reflect the repository’s separation between CLI, workflows, docs, and security configuration?

### 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/33817730978) · pi · gpt54 · 35.9 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:34 PM UTC

In the target github/gh-aw repository, first inspect existing ownership and contributor guidance, then check whether .github/CODEOWNERS or a repository-root CODEOWNERS file exists. Review ownership-relevant paths such as .github/workflows/, actions/, pkg/, docs/, and security files, and confirm maintainers’ owners before defining coverage. Done means a supported CODEOWNERS file exists with explicit owners for critical paths and the repository rules are checked for code-owner review.

Written by the indexing model from the issue text.