> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acondawayuno.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`.

```mermaid theme={null}
flowchart LR
  A["Local edit"] --> B["Validate"]
  B --> C["Exact Git stage"]
  C --> D["Commit + push"]
  D --> E["quality job"]
  E --> F["deploy job"]
  F --> G["Cloudflare Worker"]
```

## 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:

```bash theme={null}
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.

<Note>
  场景一致性测试会比较 `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.
</Note>

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

先运行：

Start with:

```bash theme={null}
git status --short
```

Then stage only the files used by the change:

```bash theme={null}
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.

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

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

## Publish / 发布

```bash theme={null}
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:

```text theme={null}
/
/?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:

```bash theme={null}
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` 历史。