1- # Workflow for deploying static content to GitHub Pages
1+ # Workflow for building and deploying the VitePress site to GitHub Pages.
2+ # Build runs on every push to develop and on every PR that touches docs (so
3+ # a build regression is caught at review time instead of breaking develop
4+ # after merge — see #7640). Deploy runs only on push: the github-pages
5+ # environment has protection rules that reject PR refs, and a PR build
6+ # never produced an artifact to deploy anyway.
27name : Deploy Docs to GitHub Pages
38
49on :
5- # Runs on pushes targeting the default branch
610 push :
711 branches : ["develop"]
812 paths :
9- - doc/** # Only run workflow when changes are made to the doc directory
10- # Allows you to run this workflow manually from the Actions tab
13+ - doc/**
14+ - .github/workflows/build-and-deploy-docs.yml
15+ pull_request :
16+ paths :
17+ - doc/**
18+ - .github/workflows/build-and-deploy-docs.yml
1119 workflow_dispatch :
1220
13- # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
1421permissions :
1522 contents : read
1623 pages : write
1724 id-token : write
1825 packages : read
1926
20- # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
21- # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
27+ # Allow only one concurrent deployment, skipping runs queued between the run
28+ # in-progress and latest queued. Do NOT cancel in-progress runs — production
29+ # deployments are allowed to complete.
2230concurrency :
2331 group : " pages"
2432 cancel-in-progress : false
2533
2634jobs :
27- # Single deploy job since we're just deploying
28- deploy :
29- environment :
30- name : github-pages
31- url : ${{ steps.deployment.outputs.page_url }}
35+ build :
3236 runs-on : ubuntu-latest
3337 steps :
3438 - name : Checkout
@@ -50,22 +54,44 @@ jobs:
5054 - uses : pnpm/action-setup@v6
5155 name : Install pnpm
5256 with :
53- version : 10.33.2
5457 run_install : false
58+ # Pin Node so the build does not silently fall back to whatever the
59+ # runner image ships with. vite 8 requires Node ^20.19.0 || >=22.12.0;
60+ # the repo declares engines.node >=22.12.0 to match.
61+ - name : Use Node.js
62+ uses : actions/setup-node@v6
63+ with :
64+ node-version : 22
65+ cache : pnpm
5566 - name : Setup Pages
67+ if : github.event_name == 'push'
5668 uses : actions/configure-pages@v6
5769 - name : Install dependencies
5870 run : pnpm install --frozen-lockfile
5971 - name : Build app
6072 working-directory : doc
6173 run : pnpm run docs:build
6274 env :
75+ GITHUB_PAGES : ${{ github.event_name == 'push' && 'true' || '' }}
6376 COMMIT_REF : ${{ github.sha }}
6477 - name : Upload artifact
78+ if : github.event_name == 'push'
6579 uses : actions/upload-pages-artifact@v5
6680 with :
67- # Upload entire repository
6881 path : ' ./doc/.vitepress/dist'
82+
83+ # Deploy to GitHub Pages on push to develop only. Kept as a separate job
84+ # because the github-pages environment's protection rules reject any
85+ # non-develop ref (including PR merge refs), which used to fail the entire
86+ # workflow at job-creation time before any build step could run.
87+ deploy :
88+ needs : build
89+ if : github.event_name == 'push'
90+ environment :
91+ name : github-pages
92+ url : ${{ steps.deployment.outputs.page_url }}
93+ runs-on : ubuntu-latest
94+ steps :
6995 - name : Deploy to GitHub Pages
7096 id : deployment
7197 uses : actions/deploy-pages@v5
0 commit comments