How this handbook is engineered
This website teaches the historical GCP delivery system in devSatym/gcp-supply-chain-security. Its own architecture lives in the separate private devSatym/gcp-security-handbook repository: Astro, Starlight, TypeScript, Markdown/MDX content, catalogue data, diagrams, and Pagefind search. The handbook has its own main branch and Git history. The GCP project’s admission and runtime controls do not protect the website build or publication process.
- Checked-in MDX, catalogues, approved evidence and an explicit report allowlist are build inputs.
- Schemas validate references; Astro renders accessible components and SVG at build time.
- Static HTML/CSS and small browser interactions are generated; Pagefind indexes production content.
- Output audits and browser checks precede an upload of dist only; manual Pages publication needs authorization.
Solid arrows indicate the stated handoff, not a claim of independent trust. Optional relationships are described in the text equivalent. Historical components are labeled in the caption.
Source, metadata, and rendering
Section titled “Source, metadata, and rendering”Pages declare their document type, audience, baseline, review date, status, related routes, controls, sources, evidence, and prerequisites. Those fields distinguish a historical implementation from the date of editorial review. Catalogue records connect a control claim to commit-pinned implementation and classified evidence; they do not turn every linked source into proof of execution.
Implementation and original-evidence links retain the original repository and full GCP revision. Edit links target the handbook’s main branch. Explicit source hashing uses a separate read-only implementation checkout through SOURCE_REPO_PATH; routine website builds do not fetch or import application history.
Astro renders MDX and custom components into static output. Starlight supplies navigation, themes, reading structure, and integrated Pagefind search. Search indexes the production output; it is not a separate paid service or a live repository query. Catalogue and route validation catch broken IDs and links before publication. Accessible diagrams accompany text explanations so meaning remains available without animation or client interaction.
MDX is trusted build input because it can import and execute code. Reviewing prose changes alone is insufficient for an untrusted contribution that adds imports or code. GitHub validation jobs have read-only repository access and no cloud credentials. Cloudflare’s Git integration separately authorizes native builds and publication, so review build inputs before merging them into the production branch.
Routing and publication
Section titled “Routing and publication”The handbook is published through native Git-integrated Cloudflare Pages Free at security.devsatym.xyz, with base /. Its assigned Pages address, gcp-security-handbook.pages.dev, remains a fallback address. Defaults live in documentation.json; production sets DOCS_SITE=https://security.devsatym.xyz. Canonical URLs, social metadata, sitemaps, search files, and assets are generated for the selected origin and base.
The Cloudflare Workers & Pages GitHub App uses selected-repository access to the private devSatym/gcp-security-handbook repository. Cloudflare account access and the GitHub App installation are separate authorization steps. The original implementation repository is not the handbook’s build or publication source. Cloudflare GitHub integration
The Pages project uses main for production, root directory website, build command npm run build:cloudflare, and output directory dist. Relevant main-branch changes start native production builds. Relevant changes on non-main branches create native previews whose generated URLs use Cloudflare’s CF_PAGES_URL. Preview builds apply indexing controls; the production origin remains the verified custom domain. The previous successful production version remains available while another build runs.
GitHub’s docs-validate.yml provides separate validation for relevant pull requests and main-branch changes. Native Pages does not automatically wait for that workflow. Review the preview and passing validation before merging; a successful local build or GitHub check alone does not establish a successful hosted deployment.
The repository remains private, while the published website is public. Native previews are public by default, and noindex controls search indexing rather than access. Publish only reviewed content and approved assets. Cloudflare preview deployments
The GitHub repository profile at https://devsatym.github.io/gcp-security-handbook and the legacy base /gcp-supply-chain-security remain compatibility targets for independent local builds and browser checks. They are not deployed to GitHub Pages; its prepared manual workflow is a historical hosting option. Earlier audits and screenshots retain their original URL and revision context.
The deployment runbook and final report below record actual checks, documentation revisions, and deployment state. This website does not need cloud service-account credentials or access to the demo cluster, and documentation pushes do not modify the original source project.
Curated engineering material
Section titled “Curated engineering material”The links below point to explicitly published, sanitized reports. Approved source-evidence captures are published through the reviewed gallery and catalogue with their historical provenance and limitations. Internal work ledgers, raw logs, unapproved captures, dependency caches, and operational state are not public handbook assets.
| Report | What it explains |
|---|---|
| Product brief | Reader needs, scope, and acceptance criteria |
| System design | Components, build flow, routing, search, and publication |
| Detailed design | Data schemas, helper contracts, and validation seams |
| UI design system | Visual tokens, component states, accessibility, and print behavior |
| Website threat model | Build-input trust, publication authority, secret leakage, and residual risk |
| Test strategy | Local validation, production browser coverage, and evidence limits |
| Deployment runbook | Local setup, Pages prerequisites, and website rollback |
| Maintenance guide | Adding records, reviewing stale content, and updating the baseline |
| Coverage map | Baseline components and their explanation/reference pages |
| Final implementation report | Delivered scope, executed checks, audit repairs, and remaining external steps |
Understand validation results
Section titled “Understand validation results”A content check can establish schema and reference integrity; a browser audit can observe search, navigation, themes, and accessibility on tested routes; a production build can establish static output. These checks do not exercise the historical GCP pipeline. Read the actual final report for versions, route coverage, measured results, unavailable checks, and publication status instead of inferring success from this architecture summary.