noxys-doc Release Flow

Authoritative reference: ADR-013 (release cadence) + this document (per-repo deployment flow for noxys-doc).

For the cross-repo feat → staging → main policy, see Release Process.

Targets

Branch	Environment	URL	Trigger
staging	Staging preview	doc-staging.noxys.cloud*	push to staging
main	Production	doc.noxys.cloud	push to main

*Cloudflare Pages preview deployment of the staging branch on the noxys-doc Pages project. Mapped via the project's custom domain settings.

Pipeline

feat/foo ──PR──► staging ──PR──► main ──tag──► doc.noxys.cloud
   │              │                │
   │              │                └─ deploy.yml (Cloudflare Pages production)
   │              └─ deploy-staging.yml (Cloudflare Pages preview)
   └─ ci.yml (build + typecheck)

Step-by-step

1. Feature branch — feat/<short-name> cut from staging.
2. PR to staging — ci.yml runs (build + typecheck). Required to pass.
3. Merge to staging — squash merge. deploy-staging.yml deploys to the staging preview URL. ci.yml also re-runs on push.
4. Manual smoke test on doc-staging.noxys.cloud — navigate critical pages (Home, Architecture, Handbook, Legal).
5. Release PR staging → main — opened when staging is green and smoke tested. Title format: release: noxys-doc YYYY-MM.
6. Merge to main — squash merge. deploy.yml deploys to production (doc.noxys.cloud).
7. Tag — calendar-versioned tag pushed by maintainer: noxys-doc-YYYY-MM (e.g. noxys-doc-2026-05).

CI/CD Workflows

Workflow	Trigger	Purpose
.github/workflows/ci.yml	PR to main/staging, push staging	Build + typecheck
.github/workflows/deploy-staging.yml	push staging, manual dispatch	Deploy to Cloudflare Pages preview
.github/workflows/deploy.yml	push main, manual dispatch	Deploy to Cloudflare Pages production
.github/workflows/dependabot-automerge.yml	dependabot PRs	Auto-merge minor/patch dependency bumps

Versioning

noxys-doc is calendar-versioned: YYYY-MM. Continuous deploy — every merge to main is published. Tags are advisory, not gated.

Hotfix flow

For broken prod (e.g. broken link, factual error in a published page):

1. Branch fix/<short-name> from main.
2. Minimum change. PR directly to main with explicit CEO/CTO approval (see Release Process — Hotfix).
3. After merge, back-port the same commit (cherry-pick) to staging so histories converge.
4. Document the incident in the Obsidian vault 01 - Journal/.

Default flow is feat → staging → main — use the hotfix path only when staging would meaningfully delay a public-facing fix.

Required secrets (org-level)

• CLOUDFLARE_API_TOKEN — scoped to noxys-doc Pages project, Pages:Edit permission only.
• CLOUDFLARE_ACCOUNT_ID — Cloudflare account ID.

Both are inherited from the organization secret store. No per-repo override.

Rollback

Production is statically built. To rollback:

1. Identify the last known-good commit on main (use the noxys-doc-YYYY-MM tags or the Cloudflare Pages deployment history).
2. Preferred: revert the offending merge commit on main via a revert PR — re-triggers deploy.yml and produces a clean audit trail.
3. Emergency: in the Cloudflare Pages dashboard, promote the previous production deployment ("Rollback to this deployment"). Then immediately open a revert PR so git matches reality.

Validation checklist

Before merging staging → main:

• ci.yml green on the latest staging commit
• deploy-staging.yml green — staging preview reachable
• Manual smoke test on doc-staging.noxys.cloud (Home, navigation, search, at least one page per top-level section)
• No onBrokenLinks: throw failures (CI catches these)
• No open BLOCKER issues against the release