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

github/gh-aw-actions should keep its current strengths—pinned Actions SHAs, a repository security policy, CODEOWNERS, and CI on the default branch—but its CODEOWNERS file is currently invalid for at least two listed owners, which can silently weaken review routing and code-owner based protections. Recommended next step: replace or remove the unresolved owners and verify the CODEOWNERS parser reports no errors.

> **Advisory only:** This review is non-binding guidance based on repository-observable evidence. It does **not** prove security, compliance, certification, endorsement, or complete alignment with GitHub Well-Architected guidance. Human review is required before acting on any recommendation.

Target repository: `github/gh-aw-actions`
Analyzed commit SHA: `49459c75b37a0b82b4ecb15e1079972cc3353bc9`
Source verification date: `2026-09-03`
Source revision: `16a9003d5c8e5a8f310d8f590ac6b6e0695e3f15` (`github/github-well-architected` default branch)
Official URLs verified:
- https://learn.github.com/well-architected/
- https://wellarchitected.github.com/
- https://github.com/github/github-well-architected
- https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
- https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions

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

## Scope, assumptions, inaccessible evidence, and limitations
- Scope is limited to the checked-out `target/` snapshot and bounded GitHub metadata for `github/gh-aw-actions`.
- Assessment uses the current GitHub Well-Architected baseline pillars: Productivity, Collaboration, Application Security, Governance, and Architecture. No baseline change was observed from the official sources above.
- GitHub Docs were used only to verify current feature behavior and prerequisites.
- Branch protection configuration and repository Actions permissions were not readable with the available token (`403 Resource not accessible by integration`), so those topics are marked `NOT_ASSESSED` or `HUMAN_REVIEW_REQUIRED` where appropriate.
- Organization- and enterprise-level practices cannot be established from repository evidence and are marked `HUMAN_REVIEW_REQUIRED` or `NOT_ASSESSED`.
- An open tracking issue with the exact existing title was not found in the review repository at assessment time.

## Pillar-to-evidence matrix

| Pillar | Status | Official page / principle | Repository evidence | Evidence limits / assumptions | Concrete improvement |
|---|---|---|---|---|---|
| Productivity | OBSERVED | GitHub Well-Architected Productivity pillar; automate routine work and keep contributor workflows efficient | `.github/workflows/sync-actions.yml` automates action syncs; `ci.yml` validates compat data and runs `zizmor`; default branch commit status is `SUCCESS` via GitHub API | Did not assess developer satisfaction, lead time, or enterprise tooling choices | Preserve the existing automation and SHA-pinned actions; keep CI coverage aligned with repository purpose |
| Collaboration | GAP_FOUND | GitHub Docs CODEOWNERS guidance; use valid CODEOWNERS to route reviews and ownership | `CODEOWNERS` contains owners `@eaftan` and `@krzysztof-cieslak`; GraphQL `codeowners.errors` reports both as `Unknown owner` on line 5 | Could not confirm intended replacement identities; only verified parser-visible invalid owners | Fix `CODEOWNERS` so every listed owner resolves and has the required access |
| Application Security | PARTIAL | GitHub Well-Architected Application Security pillar; GitHub Actions hardening guidance | `SECURITY.md` exists; `ci.yml` sets top-level `permissions: {}` and grants minimal job-level permissions; Actions are pinned to full commit SHAs; GraphQL shows `hasVulnerabilityAlertsEnabled: true` and `isSecurityPolicyEnabled: true` | Could not read branch protection or repository-wide Actions permissions; no inference about secret scanning or private alerts | Preserve least-privilege workflow permissions and SHA pinning; verify branch protection and Actions policy separately |
| Governance | PARTIAL | GitHub Well-Architected Governance pillar; ownership and policy visibility | `CODEOWNERS` exists; repository metadata exposes `custom_properties` including ownership name `@github/next`; maintenance workflow is present | Enterprise policy enforcement, rulesets, and org controls were not readable | Repair CODEOWNERS validity so ownership controls remain enforceable at repository level |
| Architecture | OBSERVED | GitHub Well-Architected Architecture pillar; keep repository structure fit for purpose | Repository purpose is narrow (`README.md`); action runtime is isolated in `setup/` and `setup-cli/`; workflow inventory is small and purpose-built | Did not assess upstream consuming repositories or broader system topology | Preserve the current focused repository boundary and explicit workflow separation |

## Prioritized improvement backlog

### 1. Repair invalid CODEOWNERS entries
- **Priority:** High
- **Status:** Untracked, evidence-backed repository improvement
- **Owner surface:** Repository maintainers
- **Official guidance:** https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
- **Evidence:** GitHub GraphQL `repository.codeowners.errors` reports:
- `Unknown owner` for `@eaftan` in `CODEOWNERS` line 5
- `Unknown owner` for `@krzysztof-cieslak` in `CODEOWNERS` line 5
- **Why this matters:** Invalid owners can prevent dependable review routing and can reduce the effectiveness of code-owner-based branch protection or reviewer automation if those protections are enabled.
- **Recommended change:** Replace unresolved usernames with valid maintainers or teams that have write access, or remove them if obsolete.
- **Dependencies / prerequisites:** Confirm the intended current maintainers or preferred owning team.
- **Acceptance checks:**
- `CODEOWNERS` contains only valid users/teams
- GitHub no longer reports `repository.codeowners.errors`
- If code-owner reviews are required in branch protection, protected-path review requests resolve to valid owners

## Strengths worth preserving
- `ci.yml` uses top-level `permissions: {}` with explicit per-job grants.
- GitHub Actions references in `ci.yml`, `sync-actions.yml`, and other workflows are pinned to full commit SHAs.
- `SECURITY.md` is present and provides a disclosure path.
- The repository has a focused architecture with a small workflow surface and clear purpose.
- Vulnerability alerts appear enabled from repository metadata.

## Human-review questions
- Are branch protection or rulesets configured to require CODEOWNERS reviews on `main`? This could increase the urgency of the invalid-owner fix.
- Should ownership move from individual users to a durable team entry to reduce maintenance churn?
- Are repository-wide Actions policies, reusable workflow trust, and approval requirements aligned with the intended risk level for a shared-actions repository?

Evidence details

### Repository snapshot evidence
- `README.md`: states the repository contains shared GitHub Actions for the gh-aw project.
- `SECURITY.md`: present with coordinated disclosure guidance.
- `.github/workflows/ci.yml`: top-level `permissions: {}`, explicit job-level permissions, SHA-pinned third-party and first-party actions.
- `.github/workflows/sync-actions.yml`: automation for synchronizing actions from `github/gh-aw`.
- `CODEOWNERS`: lists maintainers but currently includes parser-invalid owners.

### GitHub metadata evidence
- Repository metadata (`gh api repos/github/gh-aw-actions`): public repository, default branch `main`, issues enabled.
- GraphQL: `isSecurityPolicyEnabled: true`, `hasVulnerabilityAlertsEnabled: true`.
- GraphQL: default branch target `oid` `49459c75b37a0b82b4ecb15e1079972cc3353bc9` and status rollup `SUCCESS`.
- GraphQL CODEOWNERS parser results show unresolved owners on line 5.

### Inaccessible evidence
- REST branch protection endpoint: `403 Resource not accessible by integration`.
- REST Actions permissions endpoint: `403 Resource not accessible by integration`.
- Therefore branch protection details, rulesets, and some governance controls remain unverified.

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

In the target repository github/gh-aw-actions, inspect CODEOWNERS, especially line 5, and confirm which current users or team should own the listed paths. Update the entries only after maintainer identities are confirmed, then verify GitHub reports no CODEOWNERS parser errors and that protected-path review requests resolve when applicable.

Written by the indexing model from the issue text.