From d489235be080c34964f8c515331816d08faf4e79 Mon Sep 17 00:00:00 2001 From: XiaoDaiGua-Ray <51957438+XiaoDaiGua-Ray@users.noreply.github.com> Date: Fri, 6 Nov 2026 23:50:04 +0800 Subject: [PATCH] build(pages): deploy through GitHub Actions artifacts Use Ubuntu 24.04 and Node 24 Pages actions for builds from main. --- .github/workflows/ci.yaml | 33 ++++++++++++++++++++++++--------- README.md | 2 +- README.zh-CN.md | 2 +- apps/docs/guide/tooling.md | 2 +- docs/architecture.md | 4 +++- docs/toolchain-upgrade.md | 8 ++++++++ harness/README.md | 2 +- 7 files changed, 39 insertions(+), 14 deletions(-) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 93d186a3..6ec66122 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -13,14 +13,14 @@ concurrency: cancel-in-progress: true jobs: - deploy: - name: Build and publish Pages + build: + name: Build admin and documentation if: github.ref == 'refs/heads/main' - runs-on: ubuntu-latest - permissions: - contents: write + runs-on: ubuntu-24.04 steps: - uses: actions/checkout@v7.0.1 + with: + persist-credentials: false - uses: actions/setup-node@v7.1.0 with: node-version-file: .nvmrc @@ -32,8 +32,23 @@ jobs: env: RAY_TEMPLATE_SITE_ORIGIN: ${{ github.repository == 'XiaoDaiGua-Ray/ray-template' && 'https://xiaodaigua-ray.github.io' || vars.RAY_TEMPLATE_SITE_ORIGIN }} RAY_TEMPLATE_SOURCE_REF: ${{ github.sha }} - - name: Publish combined site to dist - uses: JamesIves/github-pages-deploy-action@v4.9.0 + - name: Upload Pages artifact + uses: actions/upload-pages-artifact@v5.0.0 with: - branch: dist - folder: dist/pages + path: dist/pages + include-hidden-files: true + + deploy: + name: Deploy to GitHub Pages + needs: build + runs-on: ubuntu-24.04 + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Publish Pages artifact + id: deployment + uses: actions/deploy-pages@v5.0.1 diff --git a/README.md b/README.md index df1b1345..0def8a5b 100644 --- a/README.md +++ b/README.md @@ -190,7 +190,7 @@ In the complete repository, `pnpm check` also checks server types, tests, and bu -The **Pages workflow** builds the admin and documentation on every push to `main` and publishes successful output to `dist`. It has no path filter or cross-platform check dependency; manual publication on `main` is also supported. Read [AGENTS.md](AGENTS.md) and the [Harness verification guide](harness/README.md) before contributing. Default deployment paths are `/ray-template/` for the admin and `/ray-template/docs/` for documentation. See the [deployment guidance](docs/architecture.md#deployment-and-search-discovery) before changing them. +The **Pages workflow** builds the admin and documentation on every push to `main` and publishes the `dist/pages` artifact to GitHub Pages. It also supports manual publication on `main` and runs independently of cross-platform checks. Read [AGENTS.md](AGENTS.md) and the [Harness verification guide](harness/README.md) before contributing. Default deployment paths are `/ray-template/` for the admin and `/ray-template/docs/` for documentation. See the [deployment guidance](docs/architecture.md#deployment-and-search-discovery) for Pages setup. ## Version boundaries diff --git a/README.zh-CN.md b/README.zh-CN.md index c5ad5b51..2ddc37f0 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -190,7 +190,7 @@ pnpm dev:full -**Pages 工作流**在 `main` 每次 push 后构建后台与文档,成功后发布到 `dist`。不设路径过滤,不依赖三平台检查,也支持在 `main` 手动重发。贡献前阅读 [AGENTS.md](AGENTS.md) 与 [Harness 验证说明](harness/README.md)。默认部署路径为后台 `/ray-template/`、文档 `/ray-template/docs/`,修改前请查看[部署约定](docs/architecture.md#deployment-and-search-discovery)。 +**Pages 工作流**在 `main` 每次 push 后构建后台与文档,将 `dist/pages` 产物直接发布到 GitHub Pages。它独立于跨平台检查,也支持在 `main` 手动发布。贡献前阅读 [AGENTS.md](AGENTS.md) 与 [Harness 验证说明](harness/README.md)。默认部署路径为后台 `/ray-template/`、文档 `/ray-template/docs/`,Pages 配置见[部署约定](docs/architecture.md#deployment-and-search-discovery)。 ## 版本边界 diff --git a/apps/docs/guide/tooling.md b/apps/docs/guide/tooling.md index 72cfdb10..e4f93cc4 100644 --- a/apps/docs/guide/tooling.md +++ b/apps/docs/guide/tooling.md @@ -28,7 +28,7 @@ `pnpm build` 输出 `dist/production`。将产物部署到与 `vite.custom.config.ts` 中 `base` 对应的路径。默认应用为 `/ray-template/`,域名根目录部署改为 `/`。Vite 默认打包本地依赖;可选 CDN 模式需另外确认目标环境能访问 CDN。 -组合部署使用 `pnpm pages:build`,将 `dist/pages` 作为同一个站点的产物。官方地址为 `/ray-template/`,其下 `docs/` 目录提供 v6 官网。Pages 工作流在 `main` 每次 push 后于 Ubuntu 构建,成功后发布到 `dist` 分支;不设路径过滤,也不依赖三平台检查,因此后台、文档、共享包、依赖和构建配置变动都会触发。支持在 `main` 手动重发,其他分支和 PR 不发布到正式站点。构建时传入 `RAY_TEMPLATE_SOURCE_REF`,把文档的当前源码链接固定到发布提交。 +组合部署使用 `pnpm pages:build`,将 `dist/pages` 作为同一个站点的产物。官方地址为 `/ray-template/`,其下 `docs/` 目录提供 v6 官网。Pages 工作流在 `main` 每次 push 后于 Ubuntu 24.04 构建,通过 GitHub Pages 制品部署,也支持在 `main` 手动发布。构建时传入 `RAY_TEMPLATE_SOURCE_REF`,把文档的当前源码链接固定到发布提交。使用此工作流前,在仓库 **Settings → Pages → Source** 选择 **GitHub Actions**,并确认 `github-pages` 部署环境允许 `main`。 公开生产部署可在构建环境设置 `RAY_TEMPLATE_SITE_ORIGIN` 为实际站点源地址(例如 `https://example.com`),由 base 补足路径。未配置时应用产物使用 `noindex`。公开 sitemap 列出入口页,登录后的 hash 路由用于应用交互。 diff --git a/docs/architecture.md b/docs/architecture.md index 2a36e0a5..4c969726 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -79,7 +79,9 @@ The [root configuration](../tsconfig.json) references four projects. Strict mode `pnpm build` produces admin output in `dist/production`; `pnpm docs:build` produces `apps/docs/.vitepress/dist`. `pnpm pages:build` combines them in `dist/pages`, with documentation under `docs/`. The default admin base is `/ray-template/`; the documentation base is `/ray-template/docs/`. For root hosting or another subpath, align the [admin base](../vite.custom.config.ts), [documentation base](../apps/docs/.vitepress/config.mts), and [legacy redirect targets](../scripts/assemble-pages.mjs). -Every push to `main` triggers the [Pages workflow](../.github/workflows/ci.yaml), which runs `pnpm pages:build` on Ubuntu and publishes successful output to the `dist` branch. No path filter or separate verification job gates this build, so application, documentation, shared-package, dependency, and tooling changes all trigger publication. Manual dispatch publishes only when run on `main`; generated `dist` and `frontend` branches do not trigger the workflow. The [admin public .nojekyll file](../apps/admin/public/.nojekyll) is copied into the output. Preserve it when deploying manually to Pages so assets with underscore prefixes can load. +Every push to `main` triggers the Pages workflow. The build job runs `pnpm pages:build` on Ubuntu 24.04 and uploads `dist/pages` as a Pages artifact, including `.nojekyll`. The deployment job publishes that artifact using the `github-pages` environment. Manual dispatch also publishes from `main`. [Pages workflow](../.github/workflows/ci.yaml) + +In the repository's Pages settings, set the publishing source to **GitHub Actions**. If the `github-pages` environment uses a branch allowlist, allow `main`. For manual publication from a branch, keep `.nojekyll` in the output so assets with underscore prefixes can load. [GitHub Pages source setup](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site) · [Admin .nojekyll file](../apps/admin/public/.nojekyll) For public builds, set `RAY_TEMPLATE_SITE_ORIGIN` to the actual site origin; the base supplies the path. Without it, admin production builds emit `noindex`. The public admin landing page generates canonical metadata, sharing previews, and `sitemap.xml`; authenticated hash routes are not listed as public pages. Domain-level crawling rules belong in `/robots.txt` at the site root. [VitePress mappings](../apps/docs/.vitepress/legacy.mts) generate legacy in-site links. When a site origin is configured, the assembly script also generates `dist/legacy-docs` for migrating the old site. diff --git a/docs/toolchain-upgrade.md b/docs/toolchain-upgrade.md index b3e7a42a..2cd6a729 100644 --- a/docs/toolchain-upgrade.md +++ b/docs/toolchain-upgrade.md @@ -269,3 +269,11 @@ Local verification used Node.js 26.13.0 and pnpm 12.16.1: - Reused the completed site builds for `node scripts/assemble-pages.mjs`; confirmed both entry pages, `.nojekyll`, the Mock worker, and both API contract files in `dist/pages`. Remote Actions and public deployment results were not inspected. No application rendering or asset-path behavior changed, so browser acceptance was not repeated. + +## 2026-11-06: GitHub Pages artifact deployment + +The branch publishing source (`dist` at `/`) runs a GitHub-managed workflow whose runner labels and artifact action are set by GitHub. The repository workflow now builds and deploys on `ubuntu-24.04`. It uploads `dist/pages` with `actions/upload-pages-artifact@v5.0.0` and deploys with `actions/deploy-pages@v5.0.1`. The upload action delegates to `upload-artifact` v7, and both JavaScript actions use Node.js 24. [Runner migration](https://github.com/actions/runner-images/issues/14748) · [Pages artifact release](https://github.com/actions/upload-pages-artifact/releases/tag/v5.0.0) · [Deployment action metadata](https://github.com/actions/deploy-pages/blob/v5.0.1/action.yml) + +Build and deployment use separate jobs. The build has read access to the source. Only the deploy job receives Pages and OIDC write permissions. The build keeps `.nojekyll` in the artifact and uses the same site paths and source reference. For rollout, set the repository's Pages source to GitHub Actions and allow `main` in the `github-pages` environment. [Publishing source setup](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow) + +Local validation passed `actionlint` 1.7.12 and `pnpm harness verify all`, including both production builds, 569 frontend tests, and 12 server tests. The optional real Redis test was skipped. Assembling `dist/pages` confirmed both site entry points, both API contracts, the mock worker, and `.nojekyll`. The `github-pages` environment already allows `main`. The new workflow's hosted deployment is pending the source switch. diff --git a/harness/README.md b/harness/README.md index 95038d4d..bedf9aad 100644 --- a/harness/README.md +++ b/harness/README.md @@ -59,7 +59,7 @@ For example, a CSV escaping fix can use `pnpm test:run __test__/components/table `verify` runs steps sequentially, stops at the first failure, and returns a nonzero exit code. It prints the path to `.harness-local/runs//report.json` on completion. Reports contain commands, outcomes, durations, runtime, and signals; each invocation has a separate record. Full reports represent `pnpm check` as one step; consult that run's terminal output for phase details. Invalid arguments or context, and forcibly interrupted runs, may produce no report. None of these CLI commands launches a browser. Passing command checks does not establish UI/UX acceptance. -The Pages workflow runs `pnpm pages:build` on Ubuntu for every push to `main`, then publishes the combined site to `dist`. It has no path filter or cross-platform check dependency and can also be run manually on `main`. Local full verification remains `pnpm check`; select it using the rules above. Use `pnpm lint`, `pnpm format:check`, or `pnpm typecheck` separately to diagnose failures. `pnpm lint:fix` and `pnpm format` rewrite files. `pnpm check` synchronizes icon manifests and generates `dist/production`; review generated diffs before delivery. +The Pages workflow runs `pnpm pages:build` on Ubuntu 24.04 for every push to `main`, then publishes the `dist/pages` artifact to GitHub Pages. It also supports manual dispatch on `main` and runs independently of cross-platform checks. Local full verification uses `pnpm check` according to the rules above. Use `pnpm lint`, `pnpm format:check`, or `pnpm typecheck` separately to diagnose failures. `pnpm lint:fix` and `pnpm format` rewrite files. `pnpm check` synchronizes icon manifests and generates `dist/production`. Review generated diffs before delivery. ### Browser verification