Architecture
Three-repository pipeline
Section titled “Three-repository pipeline”The documentation and governance system spans three repositories, each with a distinct responsibility:
| Repository | Role |
|---|---|
| docs-control | Central governance hub — repository settings, branch protection config, managed files manifest, reusable CI workflows, caller workflow templates, and downstream dispatch |
| docs-builder | Docker build image — Astro + Starlight build orchestration, npm dependencies, Puppeteer PDF generation, interactive components |
| docs-theme | Astro Starlight plugin — shared branding, CSS, fonts, logos, layout components, astro.config.mjs, and content.config.ts |
Content repositories only need a docs/ directory. The build container and workflow handle everything else.
Data flow
Section titled “Data flow”When a template file changes in docs-control on main:
- The dispatch workflow fires and triggers enforcement in every downstream repository
- The enforcement workflow compares desired state against current state and patches any drift
- The file sync workflow detects drifted managed files, creates a PR with canonical content, and auto-merges it
Token model
Section titled “Token model”Two fine-grained personal access tokens provide least-privilege separation:
| Token | Permissions | Used by |
|---|---|---|
REPO_SETTINGS_TOKEN | Administration R/W, Pages R/W, Contents Read, Metadata Read | enforce-repo-settings.yml, dispatch-downstream.yml |
REPO_SYNC_TOKEN | Contents R/W, Issues R/W, Pull Requests R/W, Metadata Read | sync-managed-files.yml |
The enforcement workflow needs admin access to modify branch protection and Pages settings. The sync workflow needs contents and PR access to create branches, commit files, and merge PRs. Splitting these reduces the blast radius if either token is compromised.
Self-detection
Section titled “Self-detection”Docs-control is both the provider and consumer of its own governance config. When enforce-repo-settings.yml runs on docs-control itself (via the push trigger), it detects this by comparing managed_files.source_repo against github.repository. This triggers the self_contexts override in branch protection — docs-control uses workflows directly (check name: Check linked issues), while downstream repositories use caller wrappers (check name: check / Check linked issues). See the configuration page for details on contexts vs self_contexts.
Repository layout
Section titled “Repository layout”| Directory / File | Purpose |
|---|---|
.github/config/repo-settings.json | Central config: repository settings, branch protection, Actions permissions, Pages config, and the managed files manifest |
.github/config/downstream-repos.json | Registry of enrolled downstream repositories |
.github/config/docs-sites.json | Metadata for each downstream docs site (label, URL, description) used by README templating |
.github/workflows/ | Reusable workflows: enforcement, file sync, pages deploy, linked-issue check, and dispatch |
workflows/ | Caller templates downstream repositories install into .github/workflows/ |
docs/ | Documentation source (built and deployed via Astro Starlight) |
CONTRIBUTING.md | Contributor workflow rules (synced to all downstream repositories) |
CLAUDE.md | AI assistant instructions (synced to all downstream repositories) |
README.md.tpl | Template for dynamically generated downstream README files |
.pre-commit-config.yaml | Pre-commit hooks configuration (synced to all downstream repositories) |
.markdownlint.json | Markdown linting rules |
.yamllint.yaml | YAML linting rules |