Publish through GitHub Actions

Use the canonical modify, validate, commit, and push workflow to deploy The Living Index to Cloudflare Workers.

The Living Index 的标准发布路径是：本地修改与验证、精确提交、推送 GitHub，然后由 Actions 部署 Cloudflare。Cloudflare 已配置完成后，日常工作不需要本机运行 npm run deploy。

The canonical release path is: change and validate locally, commit exact files, push to GitHub, and let Actions deploy Cloudflare. Once Cloudflare is configured, routine work does not require a local npm run deploy.

Workflow triggers / 触发条件

.github/workflows/deploy.yml runs for:

• every Pull Request;
• every push to main;
• manual workflow_dispatch.

Pull Requests only run validation. Pushes to main and manual runs deploy after validation succeeds.

Pull Request 只运行验证。推送 main 和手动运行会在验证成功后部署。

Quality job / 质量检查

The quality job uses Node 22.13.0 and runs:

npm ci
npm run typecheck
npm run lint
npm test

npm test 先创建生产构建，再运行内容 schema、Studio 上传与保存、渲染契约、场景摆放和太阳光照测试。

npm test creates a production build, then runs content-schema, Studio upload/save, rendered-contract, scene-placement, and solar-lighting tests.

场景一致性测试会比较 public/content/site-content.json 的 scene 与 app/generated/scene-config.ts。只提交 JSON 而漏掉生成场景源码会阻止部署。

A scene-consistency test compares the JSON scene with app/generated/scene-config.ts. Committing JSON without its generated scene source blocks deployment.

Files to commit after Studio work / Studio 保存后的提交文件

先运行：

Start with:

git status --short

Then stage only the files used by the change:

git add public/content/site-content.json
git add app/generated/scene-config.ts
git add public/uploads/<specific-files>
git diff --cached --check

提交内容可能还包括已删除的旧 GLB。使用 git status --short 检查 Studio 精确清理产生的删除记录。

The change may also include deletion of a superseded GLB. Review git status --short for removals produced by the Studio’s reference-aware cleanup.

不要用 git add . 隐藏范围。.content-studio-cache/、临时文件和与本次任务无关的用户改动不应进入提交。

Do not hide scope behind git add .. Do not commit .content-studio-cache/, temporary files, or unrelated user changes.

Publish / 发布

git commit -m "Update portfolio content and scene"
git push origin main

GitHub Actions uses a single production concurrency group and cancels stale in-progress runs. The newest successful main commit is the version that reaches Cloudflare.

GitHub Actions 使用单一生产并发组并取消过时运行。最终部署到 Cloudflare 的是最新成功通过的 main 提交。

Required repository secrets / 必需 Secrets

Secret	Purpose
CLOUDFLARE_API_TOKEN	Authorize Wrangler to deploy the Worker
CLOUDFLARE_ACCOUNT_ID	Select the Cloudflare account

Secrets belong in GitHub repository settings. Never write them into code, .env.example, logs, README files, or documentation.

Secrets 应保存在 GitHub 仓库设置中。不要把它们写进代码、.env.example、日志、README 或文档。

Verify a release / 验证发布

在 GitHub Actions 中打开 Validate and deploy，确认两个 Job 均成功，然后用无痕窗口检查：

Open Validate and deploy in GitHub Actions, confirm both jobs succeeded, then test in a private window:

/
/?lang=en
/?section=music
/?lang=en&section=music

普通生产路由必须忽略 Content Studio 浏览器草稿。只有显式 ?studio=1 才会恢复该 origin 的未保存草稿。

Normal production routes must ignore the Content Studio browser draft. Only explicit ?studio=1 restores unsaved work for that origin.

Roll back / 回滚

Use an auditable revert:

git log --oneline
git revert <commit-sha>
git push origin main

The revert passes through the same validation and deployment path. Avoid rewriting shared main history with git reset --hard.

回滚提交会经过同一套验证与部署流程。不要用 git reset --hard 改写共享的 main 历史。