Release, monitoring, rollback, and restore runbook

This runbook defines the production handoff boundary. It does not invent a hosting API: provider-specific deploy and rollback commands remain blocked until that provider and its immutable release mechanism are selected.

Never expose deployment tokens, GitHub tokens, user reports, local environment files, or private test logs in build artifacts or workflow output. Use least-privilege, short-lived credentials supported by the selected platform.

Required release evidence

EvidenceProducerPass condition
Locked dependency install
pnpm-lock.yaml
no unlocked resolution
Source/content gates
pnpm check
all bilingual, schema, safety, freshness, and format checks pass
Production build
pnpm build
every route, search, browser, SEO, and Lighthouse gate passes
Network report
pnpm check:external-links
zero confirmed 404/410 links; restricted/network results recorded
Staleness report
pnpm report:stale
overdue pages assigned before recommendation release
CI release artifact
quality workflow
static output and report retained with a recorded SHA-256 digest
Deployment record
provider adapter
immutable release ID, source revision, approver, UTC time

Release procedure

    Establish the candidate

    Record the source revision, Node 22.15.0, pnpm 10.34.4, lockfile checksum, xyd version, reviewer roles, and selected production adapter.

    Install and validate

    Inspect the preview

    Verify representative English and Chinese routes, native xyd search, locale switching, recovery warnings, FAQ visibility, canonical/alternate URLs, sitemap.xml, robots.txt, and llms.txt.

    Approve and deploy

    The release-engineering role records human technical/language approval, verifies the retained CI artifact against the SHA-256 digest in the quality-workflow summary, then invokes the selected provider adapter with those exact bytes. The adapter must not rebuild with floating dependencies.

    Verify production

    Check the release ID and HTTP 200 on both locale introductions, one high-risk recovery page, one database page, all discovery assets, and the favicon. Compare canonical URLs with https://steamos.club.

    Confirm the deployed origin or CDN compresses HTML, CSS, JavaScript, JSON, SVG, XML, and text responses with Brotli or gzip, sends Vary: Accept-Encoding, and applies immutable caching only to fingerprinted assets. For example:

    Do not approve a release if large text assets are transferred uncompressed; the Lighthouse budget assumes this production invariant.

Monitoring and P0 response

Monitor route availability, generated discovery assets, broken links, stale high-change content, and client errors. A P0 begins the 24-hour response SLO: freeze further releases, preserve evidence, remove or correct unsafe content, notify the accountable roles, and choose forward-fix or rollback.

Do not treat upstream crawler indexing delays, restricted link probes, or a Lighthouse variance as availability incidents without confirming production behavior.

Rollback

  1. Identify the last release whose retained artifact and evidence bundle passed the same gates.
  2. Verify that artifact against its recorded SHA-256 digest, then use the hosting provider's documented atomic release switch; do not rebuild an old revision with new dependencies.
  3. Re-run the production route/discovery smoke checks.
  4. Record incident scope, rollback release ID, UTC time, operator role, and follow-up owner.
  5. Preserve the failed artifact and reports without preserving secrets or personal data.

Backup and restore exercise

The backup set includes authored content/, schemas, dated database snapshots, templates, public assets, configuration, workflows, package-manager patch, lockfile, and the source revision. Generated .xyd/ and .generated/ output is reproducible evidence, not the primary backup.

At least annually, restore the repository into a clean environment, run the locked install and full production build, compare route counts and snapshot checksums, then publish only to an isolated preview. A restore is not considered passed until both locales, search, high-risk warnings, and rollback evidence are verified.

Frequently asked questions

Which hosting provider does this runbook assume?
Which hosting provider does this runbook assume?
None. The repository produces static xyd output. A deployment adapter must document its own immutable release identifier, health check, rollback command, credentials, and retention before production use.
Can a failed xyd command still leave apparently usable files?
Can a failed xyd command still leave apparently usable files?
Yes. The pipeline deletes old output first and independently validates every expected route and generated asset so stale files cannot be accepted as a successful release.

Sources

Version history

  • 2026-07-15: Immutable CI artifact retention, digest verification, production compression, and fingerprinted-asset cache verification added.
  • 2026-07-15: Phase 8 provider-neutral release, monitoring, rollback, and restore runbook published.