Cloudflare Pages Deployment

Cloudflare Pages hosts VyDex as static HTML, CSS, JavaScript, and JSON. Application validation and production deployment are deliberately separate: checking a commit never publishes it, creates another commit, or changes the live site. Only the protected post-validation deployment workflow may synchronize release state and publish production.

Purpose And Ownership

The workflows under .github/workflows/ own the automation boundary:

validate-application.yml checks pull requests, pushes to main, and manual validation runs.
deploy-application.yml synchronizes release state and publishes production after successful push validation on main, with explicit manual dispatch also available.
rehearse-production-rollback.yml remains a separate, confirmed maintenance exercise.

Cloudflare only hosts generated output. Canonical records, immutable snapshots, release descriptors, manifests, and retained Datasets remain owned by the repository.

What A Normal Push Does

A push to main checks out the repository with read-only permissions, installs the pinned dependency tree and Chromium runtime, then runs:

Type checking, unit tests, the Astro production build, and sitemap validation.
The Playwright and Axe browser matrix against the generated static output.

The validation workflow has no Cloudflare credentials and no write permission. It cannot run release synchronization, create a bot commit, push generated files, deploy, or roll production backward. This preserves ordinary CI as a read-only check even though successful main validation starts a separate trusted workflow.

What A Production Deployment Does

When Validate application succeeds for a push to main, GitHub automatically starts Deploy application with the validated commit SHA. Pull-request validation and failed push validation cannot start production deployment. A maintainer can also dispatch the deployment workflow manually from main for an intentional redeploy.

The trusted job checks out that exact commit with full history on a temporary branch, runs release:sync with its explicit CI authorization flag and confirmation phrase, and inspects every changed path. If public bytes changed, only generated/release-data/ is allowed; the workflow stages those paths, checks the cached diff, creates one bot commit, and later pushes it to main without force. If output is already current, no release identity or commit is created. The workflow then runs release:check and strict release:ci reproduction before either pushing or uploading. A changed main rejects the non-fast-forward bot push and stops deployment.

The deployment uses:

CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN from GitHub secrets.
CLOUDFLARE_PAGES_PROJECT_NAME and PUBLIC_SITE_ORIGIN from GitHub variables.
The protected GitHub production environment.
The non-cancelling vydex-cloudflare-pages-production concurrency group.

The workflow attaches the synchronized commit SHA and production branch name to the Pages deployment. GitHub does not emit another push-triggered workflow for a commit made with the repository GITHUB_TOKEN, which prevents the generated release commit from starting a loop.

Release Publication Is Synchronized

Deploying and selecting a new evidence-ledger release remain distinct operations composed by one trusted workflow. The maintainer commits and pushes reviewed source once. After read-only validation succeeds, deployment automatically selects a successor only when the complete public artifact changed, commits its immutable state, verifies it, and publishes that synchronized commit.

Changes that do not alter the complete public artifact create no successor and no bot commit. Local release:check, release:sync, release:next, and release:ci remain available for inspection, intentional release construction, and recovery.

Hosted Checks And Recovery

npm run verify:hosted-stage-1 remains available as an explicit diagnostic. It is not a condition inside the routine deployment workflow. Its Homepage check relies on the stable release-derived latest Entry container rather than an exact marketing headline.

The rollback rehearsal also remains manual and requires its exact confirmation phrase. Routine deployment does not search for fallback deployments or attempt automatic rollback. If a production deployment needs to be reversed, the maintainer chooses the intended successful deployment in Cloudflare and follows the restoration guide.

Failure Behavior

A failed validation run leaves Git and Cloudflare unchanged.
A failed synchronization, unexpected changed path, release check, reproduction, or bot push prevents upload.
A Wrangler upload failure leaves the workflow failed without making repository commits.
A later hosted diagnostic failure reports evidence but does not mutate production.
Recovery is a deliberate maintainer action using an identified Cloudflare production deployment, never a preview URL.

Invariants

The approved canonical origin is https://vydex.pages.dev.
The Pages project is vydex.
Workers, Pages Functions, runtime databases, and workers.dev origins remain outside the approved architecture.
Validation has read-only repository permissions and no deployment credentials.
Production deployment is automatic after successful main validation and remains manually dispatchable from main.
Deployment creates or rotates VyDex release identity only when byte comparison requires a successor and may commit only generated/release-data/.
The bot never force-pushes, and its GITHUB_TOKEN push does not recursively trigger another synchronization run.
Preview URLs never enter canonical metadata or durable records.
Cloudflare deployment history is operational state, not the evidence archive.

Implementation Landmarks

.github/workflows/validate-application.yml — read-only application checks.
.github/workflows/deploy-application.yml — trusted release synchronization and production publication.
.github/workflows/rehearse-production-rollback.yml — explicit rollback rehearsal.
wrangler.jsonc — Pages project name and static output directory.
scripts/deployment/verify-hosted-stage-one.ts — optional hosted diagnostic.
src/release/release-publication/ — explicit release construction and synchronization.