[software-development-practices:github-well-architected] TARGET_REPO repository guidance

This review is advisory and non-binding. It does **not** prove security, compliance, certification, endorsement, or complete alignment with the GitHub Well-Architected Framework. Human review is required before acting on any recommendation.

Repository `githubnext/gh-aw-workshop` would benefit most from adding repository branch protection and required pull-request review controls on the default branch. The repository already relies heavily on automation and direct-to-main publishing, but repository-observable evidence for GitHub-native change-control governance was not accessible or present in the snapshot. That creates the clearest high-confidence gap relative to current Well-Architected governance and collaboration guidance.

## Target and source metadata
- Target repository: `githubnext/gh-aw-workshop`
- Assessed target commit: `d45b06565321d2c83fa33b61cfb8045512069763`
- Source verification date: `2026-09-03`
- GitHub Well-Architected source revision: `16a9003d5c8e5a8f310d8f590ac6b6e0695e3f15`
- Official URLs used:
- `https://learn.github.com/well-architected/`
- `https://wellarchitected.github.com/`
- `https://github.com/github/github-well-architected`
- `https://github.com/github/github-well-architected/blob/16a9003d5c8e5a8f310d8f590ac6b6e0695e3f15/docs/framework-overview.md`
- `https://docs.github.com`

`[software-development-practices:github-well-architected] target=githubnext/gh-aw-workshop commit=d45b06565321d2c83fa33b61cfb8045512069763 source_rev=16a9003d5c8e5a8f310d8f590ac6b6e0695e3f15`

## Scope, assumptions, inaccessible evidence, and limitations
- Scope was limited to the checked-out `target/` snapshot and bounded public GitHub metadata for `githubnext/gh-aw-workshop`.
- GitHub Well-Architected pillar baseline was verified as: Productivity, Collaboration, Application Security, Governance, and Architecture.
- GitHub Docs was treated as the implementation source of truth only for feature verification and prerequisites.
- Repository-observable evidence cannot establish enterprise, organization, or team operating practices; those areas are marked `HUMAN_REVIEW_REQUIRED` or `NOT_ASSESSED` where appropriate.
- I could read public repository contents and some metadata, but branch protection, Actions permissions, and code scanning alert endpoints returned `403 Resource not accessible by integration`; those controls are therefore not directly verified.
- No open tracking issue with the exact current assessed target commit and framework source revision was found in `githubnext/gh-aw-cao` at review time.
- This review omits secure-development lifecycle, provenance, vulnerability response, and similar SSDF-oriented remediations unless directly necessary for GitHub Well-Architected provenance.

## Pillar-to-evidence matrix

| Pillar | Status | Official source and topic | Evidence | Limitations / assumptions | Concrete improvement |
| --- | --- | --- | --- | --- | --- |
| Productivity | OBSERVED | GitHub Well-Architected Framework Overview → Productivity pillar | Repository contains extensive GitHub Actions automation under `.github/workflows/`, reusable agentic workflow sources (`.md` plus `.lock.yml`), and local docs build automation in `scripts/build-docs.js` and `deploy-pages.yml`. | Workflow effectiveness and developer satisfaction were not measured. | Preserve the current automation-first pattern and document maintenance ownership for critical workflows. |
| Collaboration | PARTIAL | Framework Overview → Collaboration pillar | Repository enables issues, pull requests, projects, wiki, and contains Markdown lint and image-link workflows that file issues when failures happen. | Branch review requirements and merge controls were not readable via API. | Require pull-request review on `main` so the existing collaboration surface becomes an enforced control, not just an available one. |
| Application Security | PARTIAL | Framework Overview → Application Security pillar | Workflows use pinned action SHAs in several key workflows such as `deploy-pages.yml`, `markdown-lint.yml`, and `agentics-maintenance.yml`; repository includes security-focused content and a `security-side-quest` workflow source. | Code scanning and security configuration endpoints were inaccessible; secret scanning, Dependabot, and alert handling are `NOT_ASSESSED`. | Keep SHA pinning as a strength and add branch protection so workflow or content changes cannot bypass review before deployment. |
| Governance | GAP_FOUND | Framework Overview → Governance pillar (permissions, access controls, controls) | `deploy-pages.yml` publishes from pushes to `main`; repository metadata shows broad collaboration features enabled; repository snapshot shows no repository-local evidence of enforced review gates, and branch-protection API access was denied rather than confirming protection. | A hidden protection rule may exist, so final confirmation requires maintainer review; still, no observable evidence confirms the recommended control. | **Prioritize enabling branch protection / rulesets for `main` with required pull-request review, status checks, and restricted direct pushes.** |
| Architecture | PARTIAL | Framework Overview → Architecture pillar | Repository has a clear documentation-site architecture: source workshop Markdown, build scripts, Pages deployment workflow, SVG QA workflows, and agentic workflow configuration under `.github/workflows/aw.json`. | Reliability settings such as environment protections and disaster recovery are not fully visible. | Add required checks on the deployment path to improve release reliability for the documentation site architecture. |

## Prioritized improvement backlog

1. **Enable default-branch protection or an equivalent ruleset for `main`.**
- **Priority:** P1
- **Status:** `GAP_FOUND`
- **Official provenance:** GitHub Well-Architected Governance and Collaboration pillars; GitHub Docs for branch protection / rulesets implementation.
- **Evidence:** `deploy-pages.yml` deploys on every push to `main`; repository exposes direct collaboration features (`has_issues`, `has_pull_requests`, `has_projects`, `has_wiki`); branch-protection verification endpoint was inaccessible, leaving no observable evidence that changes to published workshop content and workflow definitions require review.
- **Rationale / maintainer benefit:** This is the strongest repository-owned control to reduce accidental or unreviewed changes to workshop materials, workflow automation, and GitHub Pages publishing. It also makes existing lint and QA workflows materially enforceable.
- **Owner surface:** Repository maintainers / admins.
- **Dependencies / prerequisites:** Admin access to repository settings. If org-level rulesets are already applied, document that fact and ensure this repository is targeted.
- **Recommended minimum acceptance checks:**
- `main` requires pull requests for normal changes.
- At least one approving review is required.
- Critical checks such as markdown lint, image-link validation, and relevant SVG/documentation checks are required before merge.
- Direct pushes to `main` are restricted except for narrowly justified automation.
- Force-push and deletion protections are enabled for `main` unless a documented exception exists.

2. **If branch protection is already enforced elsewhere, document the governing ruleset in repository-facing maintainers' docs.**
- **Priority:** P2
- **Status:** `PARTIAL`
- **Evidence:** The repository snapshot contains contributor-facing docs but no obvious maintainer note describing required checks or protected-branch expectations.
- **Rationale / maintainer benefit:** Reduces ambiguity for workshop contributors and helps preserve governance as the repository scales.
- **Owner surface:** Repository maintainers.
- **Dependencies:** Best paired with item 1.
- **Acceptance checks:** A maintainer-facing document or README section states the protected branch path, required checks, and any automation exceptions.

## Strengths worth preserving
- Strong automation footprint with many targeted GitHub Actions workflows.
- Important workflows pin third-party actions to immutable SHAs, reducing supply-chain drift risk.
- Documentation publishing is codified in version control rather than performed manually.
- The repository includes explicit workshop and agentic-workflow guidance, which supports contributor onboarding.

## Human-review questions
- Is `main` already covered by an organization-level ruleset or branch protection that this token could not read?
- Which workflows are intended to be required status checks for merges into `main`?
- Are there any automation accounts that legitimately need direct push access, and if so can that access be narrowly scoped?
- Should Pages deployment be coupled to merge-to-main only, or also to environment approval protections?
- Are Application Security controls such as Dependabot alerts, code scanning, and secret scanning already configured at organization level for this repository?

### 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/33817820031) · pi · gpt54 · 25.1 AIC · ⌖ 8.5 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 .github/workflows/deploy-pages.yml, markdown-lint.yml, and the image-link and SVG/documentation checks to identify the checks relevant to main. Confirm whether organization-level rulesets already apply, then configure or document protection requiring pull requests, one approval, required checks, and restricted direct pushes. Done means the maintainer acceptance checks are enforced or the governing ruleset is documented in maintainer-facing docs.

Written by the indexing model from the issue text.