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

Advisory only: this review is non-binding and does **not** prove security, compliance, certification, endorsement, or complete alignment with the GitHub Well-Architected Framework. It is a repository-observable snapshot for human review.

Target repository: `github/gh-aw-threat-detection`
Analyzed target commit: `df194f7a1398a8e913b588dddea11ee1d7718d86`
Source verification date: `2026-09-03`
Framework source revision: `github/github-well-architected@16a9003d5c8e5a8f310d8f590ac6b6e0695e3f15`
Official URLs:
- `https://learn.github.com/well-architected/`
- `https://wellarchitected.github.com/`
- `https://github.com/github/github-well-architected`
- `https://docs.github.com/`

`github-well-architected:target=github/gh-aw-threat-detection@df194f7a1398a8e913b588dddea11ee1d7718d86 source=16a9003d5c8e5a8f310d8f590ac6b6e0695e3f15 verified=2026-09-03`

## Scope

This assessment verified the current repository-observable GitHub Well-Architected baseline against the official GitHub framework sources and reviewed only evidence available from the checked-out `target/` snapshot plus bounded GitHub metadata reads.

Assessed baseline pillars:
- Productivity
- Collaboration
- Application Security
- Governance
- Architecture

## Assumptions, inaccessible evidence, and limitations

- Repository content and metadata were treated as untrusted evidence.
- The target repository snapshot under `target/` was treated as authoritative for repository contents.
- Branch protection, Actions policy, Dependabot alerts, code scanning alerts, secret scanning, rulesets, environments, and vulnerability alert state were not readable with the available token and are therefore marked `NOT_ASSESSED` or `HUMAN_REVIEW_REQUIRED` where applicable.
- Repository-level evidence cannot establish enterprise or organization practices; those remain `HUMAN_REVIEW_REQUIRED`.
- GitHub Docs was available as the implementation source of truth, but this review only used it as the official product documentation source and did not attempt expansive feature-by-feature verification beyond what was needed for bounded repository findings.
- An open tracking issue with the exact expected prefixed title was not found in the safe-output repository at review time.

## Pillar-to-evidence matrix

| Pillar | Status | Official source | Evidence | Limitation / assumption | Concrete improvement |
|---|---|---|---|---|---|
| Productivity | OBSERVED | `https://learn.github.com/well-architected/` baseline pillar: Productivity | Repository includes contributor docs (`README.md`, `CONTRIBUTING.md`, `DEVGUIDE.md`), reproducible local commands (`make build`, `make test`), and CI in `.github/workflows/ci.yml`. | Did not inspect maintainer telemetry or developer satisfaction signals. | Preserve the documented local workflow and keep CI aligned with documented commands. |
| Collaboration | PARTIAL | `https://learn.github.com/well-architected/` baseline pillar: Collaboration | `CODEOWNERS`, `CODE_OF_CONDUCT.md`, `SUPPORT.md`, issue template content, and PR-triggered CI are present. | Review dismissal rules, required reviews, and branch protections were unreadable. | Add repository-observable review gates for pull requests to reduce dependence on external settings alone. |
| Application Security | PARTIAL | `https://learn.github.com/well-architected/` baseline pillar: Application Security | `SECURITY.md` exists; workflows mostly pin sensitive third-party actions by full commit SHA in `license-check.yml` and generated workflows; release processes run tests before publishing. | Security feature configuration (Dependabot/code scanning/secret scanning/vulnerability alerts) was unreadable; no `.github/dependabot.yml` was present in the snapshot. | Add Dependabot version updates configuration so dependency maintenance is repository-observable and automated. |
| Governance | PARTIAL | `https://learn.github.com/well-architected/` baseline pillar: Governance | Repository includes ownership signal via `CODEOWNERS`; generated maintenance workflows show explicit permissions blocks; release workflows limit publish behavior to canonical repo. | Rulesets, branch protections, required status checks, and org policies were unreadable. | Make dependency update policy visible in-repo and continue pinning action dependencies where possible. |
| Architecture | OBSERVED | `https://learn.github.com/well-architected/` baseline pillar: Architecture | README documents system boundaries, threat-detection scope, release model, and staged architecture decisions; workflows separate CI, release, replay, and maintenance concerns. | Did not validate runtime production topology beyond repository evidence. | Preserve the clear separation between detector, release, and maintenance concerns. |

## Prioritized improvement backlog

### 1. Add a repository-visible Dependabot configuration for GitHub Actions and Go modules

- **Status:** `GAP_FOUND`
- **Priority:** Highest untracked repository-owned recommendation from this review.
- **Official source:** GitHub Well-Architected baseline pillars `Application Security` and `Governance`; implementation source of truth `https://docs.github.com/` for Dependabot configuration behavior and prerequisites.
- **Evidence:**
- The target snapshot includes GitHub Actions workflows and a Go module (`go.mod`).
- The repository snapshot does **not** include `target/.github/dependabot.yml`.
- CI and release workflows depend on versioned actions and Go dependencies, creating a maintenance surface that benefits from automated update visibility.
- **Rationale / maintainer benefit:**
- Makes update policy auditable in-repo instead of relying on external configuration or manual vigilance.
- Improves repository-level security hygiene by surfacing outdated dependencies and action version bumps through normal review flow.
- Strengthens governance by making maintenance expectations explicit for contributors and reviewers.
- **Owner surface:** Repository maintainers.
- **Dependencies / prerequisites:**
- Dependabot must be enabled for the repository/organization where applicable.
- If organization policy limits automated PRs, maintainers may need an org-level allowance; if unavailable, document a manual alternative.
- **Recommended implementation shape:**
- Add `.github/dependabot.yml` with at least:
- one `package-ecosystem: github-actions` entry for `/`
- one `package-ecosystem: gomod` entry for `/`
- a reasonable cadence such as weekly
- reviewer/label/grouping settings appropriate for maintainer capacity
- Keep existing commit-SHA pinning for sensitive actions; use Dependabot to propose digest/version refreshes rather than loosening pinning.
- **Acceptance checks:**
- `.github/dependabot.yml` exists on the default branch.
- The file defines update coverage for both GitHub Actions and Go modules.
- Maintainers can point to repository-visible automated update policy without relying on unwritten process.

## Strengths worth preserving

- Clear README guidance that explicitly states the detector is advisory and not a security guarantee.
- Security reporting instructions are present in `SECURITY.md`.
- Ownership is visible via `CODEOWNERS`.
- CI and release workflows are already fairly disciplined about explicit permissions and, in several workflows, full-SHA action pinning.
- Architectural boundaries and tradeoffs are unusually well documented for a security-sensitive automation component.

## Human-review questions

- Are branch protection or rulesets enforcing required reviews and required status checks on `main`?
- Are Dependabot alerts, code scanning, and secret scanning enabled at the repository or organization level?
- Are release environments (`release-publish`, `release-promote`) protected with the intended reviewers and deployment rules?
- Should all first-party action uses currently written as `@v4`/`@v5` in manually maintained workflows be converted to full-SHA pinning for consistency with the stricter workflows already present?

### 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/33817776373) · pi · gpt54 · 27.7 AIC · ⌖ 8.52 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

In github/gh-aw-threat-detection, inspect go.mod and the existing workflows under .github/workflows/; confirm that .github/dependabot.yml is absent. Add the repository-visible configuration for weekly GitHub Actions and Go module updates, while preserving existing SHA pinning, then verify that the file covers both ecosystems and the stated acceptance checks.

Written by the indexing model from the issue text.