Production Capstone: Govern a GitHub Organization and Build a Secure End-to-End Delivery System: Requirements, Constraints, and Target Architecture

1. The capstone problem: make GitHub operable, not merely configured

A production GitHub platform is not a pile of enabled features. It is a delivery system in which human identities, repository state, automation identities, release artifacts, security findings, and evidence all have explicit owners and boundaries. Earlier chapters introduced these pieces separately. The capstone starts by asking a harder question: what must remain true when they interact, fail, or are operated under time pressure?

Before choosing a ruleset, runner, package registry, secret store, or scanning feature, write requirements in observable terms. “Use secure CI” is not testable. “Pull-request jobs receive only read access to repository contents; release provenance is produced only from a manual run on main; consumers verify the exact artifact digest” is testable.

2. Convert goals into acceptance requirements

These requirements deliberately mix product controls and operating practices. GitHub can enforce some statements directly; others—such as who is allowed to invoke emergency procedure or how rapidly an exception expires—remain team policy and must be backed by evidence.

3. Target architecture: control plane, execution plane, artifact plane, evidence plane

flowchart TD
I[Issue / requirement] --> PR[Pull request]
PR --> RS[Repository ruleset]
PR --> CI[Hosted Actions: verify]
RS --> M[Merge to main]
CI --> M
M --> RD[Manual release-evidence run]
RD --> A[Immutable artifact bytes + SHA-256]
RD --> AT[GitHub artifact attestation]
A --> R[GitHub Release]
AT --> V[Consumer verification]
R --> V
PR --> E[Evidence inventory]
CI --> E
RS --> E
RD --> E
R --> E

The arrows are causal claims that the capstone will verify. A PR does not become a release merely because CI was green. Merge creates a source commit. A release run binds artifact bytes to that commit. A release record references those bytes. The consumer independently checks both the release tag target and the artifact attestation.

4. Identity and trust boundaries

flowchart TB
H[Human account] -->|issue / PR / review| GH[GitHub repository]
GH -->|event| R[GitHub-hosted runner]
R -->|job-scoped| T[GITHUB_TOKEN]
R -->|release job only| O[GitHub OIDC identity]
O --> AT[Attestation signing service]
T --> API[Repository API]
AT --> C[Consumer verification]
EXT[Optional cloud / registry] -. not required .-> O

Authentication answers “which identity made this request?” Authorization answers “what may it do?” A valid workflow identity is not automatically trusted to deploy production. Likewise, a valid artifact attestation proves a signed provenance statement about bytes; consumer policy still decides whether the repository, workflow, ref, runner class, and digest are acceptable.

5. Repository and organization topology

Multi-repository architecture is not inherently more mature. Splitting repositories adds independent permissions, releases, dependency edges, API calls, and incident scope. A monorepo adds path ownership and selective-CI complexity. The capstone keeps the free path intentionally small so each control can be proved.

6. Change and release governance

• Issue: captures requirement, risk, acceptance criteria, and owner before implementation.
• Pull request: carries a bounded diff and exposes the exact head SHA under review.
• Ruleset: makes the intended merge policy machine-enforced. The capstone requires a pull request and a stable verify status check after that check has run successfully in the repository.
• Review: in the solo mandatory lab, review is a recorded checklist rather than independent approval. In an organization, require qualified reviewers/CODEOWNERS where supported and operationally appropriate.
• Release: a release points to a known source commit and publishes exact artifact/digest evidence. Mutable labels are not substituted for immutable identity.
• Emergency path: never assume “admins can bypass” is a recovery plan. Define who may invoke emergency procedure, what evidence must be preserved, what temporary relaxation is allowed, how long it lasts, and how normal policy is restored.

7. Security baseline and incident responsibilities

8. Business continuity assumptions

Recovery is designed before the incident. The capstone defines six continuity cases:

1. Ruleset/required-check deadlock: inspect which rule and check are blocking; repair the check or use a pre-authorized, time-bounded emergency procedure rather than improvising a bypass.
2. Failed release: stop promotion, identify last known-good commit and artifact digest, and publish/restore from known evidence. Do not move an existing release tag silently.
3. Credential compromise: revoke/rotate first. Git history cleanup is secondary containment because deleting bytes does not invalidate a credential already copied.
4. Runner compromise: stop affected jobs, revoke reachable credentials/tokens, isolate the runner/network, preserve logs, and rebuild on a trusted runner. The mandatory lab uses hosted runners and simulates this scenario.
5. Residual access: resolve all additive access paths—direct grant, teams, base permission, app installation, deploy keys/tokens—then verify effective access independently.
6. Repository/organization loss: source history alone is not the whole service. Preserve release artifacts/evidence, policy-as-code, runbooks, ownership contacts, external dependencies, and restore procedures.

9. Availability map before implementation

Knowledge checks

Summary

The capstone architecture is deliberately evidence-centered. It has separate change, execution, release, provenance, and evidence planes; explicit human and automation identities; a mandatory public/free implementation; and an extension map for controls that need an organization, paid product, or external system. Lesson 2 now builds the disposable system and proves each state transition.

Official references

• GitHub Docs — GITHUB_TOKEN
• GitHub Docs — OIDC
• GitHub Docs — Code scanning
• GitHub Docs — Secret scanning
• GitHub Docs — Artifact attestations
• GitHub Docs — REST API