03 — Deployment & Management

Pipeline

Local edit → git push → GitHub PR
   ↓
GitHub Actions: mkdocs build --strict (validates links, syntax)
   ↓
Cloudflare Pages: build preview deployment for the PR
   ↓
Reviewer reads preview URL (gated by Access)
   ↓
Merge to main → Pages builds production → docs.adventive.dev

GitHub Actions workflow

.github/workflows/build.yml:

name: Validate docs build
on:
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install -r requirements.txt
      - run: mkdocs build --strict   # fails on broken links, missing files

Strict mode catches broken internal links before they hit production. This is the single most useful CI gate — Markdown drift across 50+ files will produce broken links eventually.

DNS & TLS

• DNS: docs.adventive.dev CNAME → adventive-engineering-docs.pages.dev (Cloudflare creates this automatically when the custom hostname is added to the Pages project; the zone is already on Cloudflare).
• TLS: handled by Cloudflare. Universal cert. The .dev TLD is on the HSTS preload list — every connection is HTTPS by default.
• WAF: default Pages protections. No additional rules needed for a static site.

Observability (per house standard, telemetry against New Relic)

For a static read-only site, the bar is low — but follow the house standard of designing telemetry intentionally:

Signal	Source	Why it matters
Request volume + 4xx/5xx rate	Cloudflare Pages analytics (free)	Tells us whether the site is reachable and being read
Access denials	Cloudflare Access logs	Detects unauthorized attempts; confirms the gate works
Build failures	GitHub Actions + Pages build status	Catches mkdocs errors before content drifts
Page-level engagement (optional)	New Relic Browser agent	Only add if a stakeholder asks for “which docs are read” — otherwise overkill

Default: skip the New Relic Browser agent for v1. Re-evaluate after 90 days if engagement data becomes a business question.

Backup & recovery

The repo IS the backup. GitHub holds full history. To restore from total loss:

1. git clone git@github.com:adventive/adventive-engineering-docs.git
2. Reconnect Pages to the repo
3. Reapply Cloudflare Access policy (saved as code in this folder; see 04-runbook.md)

RTO: < 30 minutes. RPO: 0 (last commit).

Rollback

Cloudflare Pages keeps deployment history. To roll back: Pages → Deployments → pick prior good deployment → “Rollback to this deployment”. Fast and reversible — no DNS change required.

Cost

Component	Cost
Cloudflare Pages	$0 (free tier covers our volume by ~1000x)
Cloudflare Access	$0 incremental (covered by existing Zero Trust seats)
GitHub Actions	$0 (private repo, well within free minute allowance)
Domain	already owned
Total	~$0/month