0005 · Deployment walkthrough

English is authoritative; Chinese reference .

Status: prepared locally from main a3c0704b74c2e3daa2235e2bb0fb934d5fb0c2a1, following the Fieldnotes delivery . No PR, commit or remote configuration change in this task.

Review selection: the owner waived requirements, plan, execution and acceptance reviews for this change. No independent review pass is claimed.

Requirements

Make the existing deployment guide usable by a first-time operator. Keep the English guide authoritative and the Chinese guide equivalent. Explain account prerequisites, the purpose of each key step, exact setting locations and values, the free private-repository PR process, first release, custom-domain cutover, observable success, failure recovery and rollback. Separate local checks from unverified external setup. Deliver the required ignored Chinese acceptance handbook.

The scope is documentation, including the linked workflow guide’s explanation of plan-dependent enforcement. Preserve application code, workflows, dependency pins and production settings. Reading official documentation and remote main is permitted; account changes, credential creation, pushes and deployment are outside this task.

Plan and decisions

Expand the existing guide instead of introducing another deployment mechanism or duplicating environment installation. Reuse the development and workflow guides. Use one worked domain/Worker example, explicitly labeled as an example, and give each stage a completion condition.

Keep GitHub Actions as the release authority. Establish the Cloudflare account and workers.dev subdomain, let the first CI deployment create the named Workers, inspect those URLs, then attach production domains. This removes the circular instruction to create and bind already-deployed Workers before the first release. Preserve the distinction between build-time URL variables and Cloudflare domain routing.

Validate relative links, bilingual coverage, whitespace, privacy and the rendered log-site output. Do not add tests that merely assert document wording. No dependency upgrade is involved. Official UI instructions are checked on 2026-09-17 and linked at the relevant steps.

The primary route keeps the repository private on GitHub Free. Rulesets and GitHub Environments are not prerequisites; PRs and successful checks remain contributor obligations, with no claim of server-side enforcement. Repository-level secrets replace environment-secret instructions. The guide supplies the exact one-line workflow change needed before activation, but the current CI file remains unchanged. Paying for Team or making the repository public is not required by this route.

Execution

Replaced the abbreviated setup notes with matching 11-section English/Chinese walkthroughs. They cover prerequisites, local verification, the deployment switch and free-plan PR process, account/DNS preparation, repository secret and variable locations, first publication, domain cutover, live checks, retries, rollback and 16 troubleshooting cases. Each setup stage has an observable completion condition; five tables give names, values and responsibilities.

The deployment behavior descriptions match the existing source: only main push events can publish, site URLs are repository variables used during build, the deployment switch alone triggers nothing, no manual dispatch exists, artifacts expire after 7 days, stale reruns skip, and uploads can leave one site updated. Dashboard-managed domains remain distinct from the build URLs. No application, workflow or dependency files changed. Activation on the free private plan still requires a separate approved change removing jobs.deploy.environment: production; the tutorial labels that prerequisite explicitly and retains the main/checks/lock/SHA safeguards. Key-step explanations distinguish variables from secrets, environments from servers, and nameserver delegation from Worker domain routing.

Acceptance and migration

Local verification on 2026-09-17 used the pinned Node.js 26.8.2, pnpm 12.4.1, Go 1.27.1 and Hugo Extended 0.166.0. pnpm install --frozen-lockfile --offline reused the locked dependencies; pnpm tools:hugo installed the verified pinned binary. The initial pnpm build passed. After the free-plan revision, pnpm build:logs and all 6 pnpm test:output checks passed, including generated local links; portfolio source and its previously built output were unchanged. The new change record and deployment guide exist in both language outputs.

Source checks covered 22 relative links across the six changed public documents, matching bilingual shell/YAML examples and numbered sections, whitespace and private-path exclusion. The illustrated deploy-job prefix exactly matches the current source with only its environment line removed; the actual CI file remains unchanged. Chromium checks at 1440px and 390px verified both guides’ 11 sections, rendered emphasis, language navigation, Chinese search for the free-plan text and no page overflow; all five Chinese tables remained accessible at phone width. Screenshots were inspected locally and are not public evidence attachments. The Chinese acceptance handbook is ignored, untracked and outside Hugo mounts; its exact path is absent from public HTML.

The complete application suite and deployment dry run were not rerun for this documentation-only change. External GitHub enforcement, token permissions, uploads, DNS, TLS and live-page acceptance remain unverified. No independent reviews ran, as selected above.

For later free-plan activation, add the two Cloudflare values as repository secrets, remove the deploy job’s environment reference through a checked PR while deployment is disabled, then confirm main has the change before enabling uploads. If replacing a token, validate the new credential before revoking the old one. Reintroducing the environment reference would require a supporting plan and configured environment; it is not a usable rollback on the free private plan.

No migration required for this documentation change: it changes neither dependencies nor configuration, source content schemas, application routes, data or deployment behavior. The guide separately describes the backups, cutover and recovery required when an operator later activates hosting. After a commit, document rollback is a normal revert PR; preserve any ignored local handbook before removing the worktree.