build(pages): deploy through GitHub Actions artifacts

Use Ubuntu 24.04 and Node 24 Pages actions for builds from main.
This commit is contained in:
XiaoDaiGua-Ray 2026-11-06 23:50:04 +08:00
parent 19ac1805a5
commit d489235be0
No known key found for this signature in database
7 changed files with 39 additions and 14 deletions

View File

@ -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

View File

@ -190,7 +190,7 @@ In the complete repository, `pnpm check` also checks server types, tests, and bu
<!-- fullstack:end -->
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

View File

@ -190,7 +190,7 @@ pnpm dev:full
<!-- fullstack:end -->
**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)。
## 版本边界

View File

@ -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 路由用于应用交互。

View File

@ -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.

View File

@ -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.

View File

@ -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/<run>/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