fix(ci): make the docs deploy deterministic and gate it on pull requests - #209
Merged
Conversation
The docs deploy has failed on every 3.x push since 2026-08-08. Two causes: `docus` was declared as `latest`, which npm normalises to `*` in the lockfile. `npm ci` re-resolved it against the registry on every run, so its transitive tree drifted out of the lockfile and the install died with EUSAGE (`Missing: oxc-parser@... from lock file`) at a version that tracked the run date. Pinning it to `^5.9.0` makes the install reproduce the lockfile. `better-sqlite3` was a direct `^13` dependency while docus peer-requires `12.x`, so the last dependabot group bump made `npm ci` fail with ERESOLVE. It is not imported by the docs; it only exists to satisfy that peer, and npm installs peers automatically, so dropping it keeps it aligned with docus. Nothing verified the docs build before merge: deploy-docs.yml only runs on push, so auto-merge landed dependabot PRs on the PHP suite alone and the breakage surfaced after the merge. A Docs workflow now builds the site on every pull request, and a `Tests passed` job aggregates the test matrix under a name that survives matrix changes, so both can be required checks. Node moves to 24: nuxt requires ^22.19.0 || ^24.11.0 || >=26.0.0 and the runner was on 20, which is past EOL and already emitted EBADENGINE warnings.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The docs deploy has failed on every
3.xpush since 2026-08-08 (08-08, 08-12, 08-19, 08-20, 08-30). Each failure was patched by hand or left standing; this fixes the causes.Why it kept breaking
docuswas declared aslatest. npm normalises that to*in the lockfile, sonpm cire-resolved docus against the registry on every run instead of reproducing the lockfile. Its transitive tree then drifted and the install died withEUSAGE: Missing: oxc-parser@X from lock file, where X tracked the run date (0.143.0 on 08-08, 0.144.0 on 08-12, 0.146.0 on 08-19). Pinning to^5.9.0makesnpm cideterministic. The resolved version is unchanged at 5.9.0.better-sqlite3was pinned to^13against a12.xpeer. docus 5.9.0 peer-requiresbetter-sqlite3@12.x; the 08-29 dependabot group bump took the direct dependency to 13.0.3, sonpm cifailed withERESOLVE. It is not imported anywhere indocs/, it exists only to satisfy that peer, and npm installs peers automatically. Dropping the direct dependency keeps it tracking docus (12.11.1 is now resolved as a peer) and stops dependabot from proposing the conflict again.Nothing verified the docs build before merge.
deploy-docs.ymlonly runson: push, so dependabot PRs touchingdocs/**were auto-merged on the strength of the PHP suite alone and the breakage only surfaced afterwards, on the deploy.Changes
docs/package.json: pindocusto^5.9.0, drop the directbetter-sqlite3dependency; lockfile regenerated..github/workflows/docs.yml(new): builds the docs on every pull request to3.x, mirroring the build half of the deploy..github/workflows/tests.yml: add aTests passedjob that aggregates the matrix under a name that survives matrix changes, so it can be a required check without going stale when the PHP/Laravel versions move..github/workflows/deploy-docs.yml: Node 20 to 24. nuxt requires^22.19.0 || ^24.11.0 || >=26.0.0; the runner was already emittingEBADENGINEwarnings on 20, which is past EOL.The two new job names are intended to become required status checks on
3.x. Without themgh pr merge --autodoes not wait for anything, which is what let the broken lockfile land.Verification
Reproduced the exact
ERESOLVEfailure locally against3.x, then on this branch, on Node 24.20.0:rm -rf node_modules && npm cisucceeds.NUXT_APP_BASE_URL=/custom-fields/ NUXT_SITE_URL=https://relaticle.github.io DOCS_VERSION=3.x npm run generatesucceeds, prerendering 53 routes into.output/public.node_modules/better-sqlite3resolves to 12.11.1 with its native binding built.The per-page OG image warnings (
[400] Invalid island request hash) are pre-existing and do not fail the build: the last successful deploy on 2026-07-28 also produced no_og/output ongh-pages. Not addressed here.