ADR 0003 — Deployment strategy

Status. Accepted (2026-05-27) Authors. [email protected]

Context

sigmashake-docs needs a deployment path that's repeatable, reviewable, and verifiable post-deploy. We don't want to invent a custom CI flow per service.

Decision

Amended 2026-10-10. The original text named wrangler deploy and a /api/health probe. The site is static Cloudflare Pages and serves no API. The text now matches package.json.

Deploy via bun run deploy, which calls shared/agent-config/scripts/deploy-guarded.sh --check. The strict check that the working tree matches origin/main is opt-in: set SSG_DEPLOY_STRICT=1.

• Build: docusaurus build pre-renders the static site to build/.
• Upload: wrangler pages deploy build --project-name sigmashake-docs --branch main.
• Verification: load the changed page on docs.sigmashake.com and check that search returns results. The site serves no /api/health endpoint.
• Sentinel: .last-deploy-result records the outcome for the cert scanner.
• Rollback: re-deploy the previous tag from git.

Alternatives considered

1. Per-service GitHub Actions workflow. Considered; rejected — too many opinionated YAML files to maintain. We'll revisit when more engineers deploy.
2. Manual deploys without sentinels. Tried briefly; broke the cert scanner's deploy-recency signal. Won't revisit.

Consequences

• With SSG_DEPLOY_STRICT=1, the deploy gate (deploy-guarded.sh) refuses to deploy a tree that differs from origin/main.
• A failed deploy leaves the sentinel as fail, which drops the service out of cert tier within the cert TTL.

Revisit

When the number of people with deploy rights grows, or when a customer SLA requires a formal change-management process (e.g. SOC 2 CC8.1).