githubnext / githubnext/gh-aw-cao
[self-care:docs-build-time-investigator] Drop the extra node_modules cache from docs Pages builds
- Dominant language
- JavaScript
- Stars
- 3
- Forks
- 1
- Avg merge
- 49m
- Merged PRs (30d)
- 837
Description
### Summary
The docs Pages workflow is already getting dependency cache hits, but it still spends a median 6 seconds per run restoring a separate `node_modules` cache that never leads to `npm ci` in the current sample. Across 20 successful `docs.yml` runs in the last 14 days, median workflow execution was 93.5 seconds (p90 115.3), and the `build` job spent a median 28.0 seconds (p90 32.2). The dependency path is now pure overhead rather than the bottleneck it was designed to avoid.
### Timing evidence
Evidence window: the latest 20 completed successful `docs.yml` runs returned by GitHub Actions within the last 14 days, including run IDs `34195454259`, `34194868768`, `34192990125`, `34192616762`, `34192480725`, `34192397470`, `34191999856`, `34191890934`, `34191085336`, and `34190459618` as directly inspected samples.
Comparable successful sample size: 20 workflow runs; 10 runs were step-inspected in detail.
Measured execution durations:
- Full `docs.yml` workflow: median 93.5s, p90 115.3s
- `dashboard` job: median 44.5s, p90 48.1s
- `build` job: median 28.0s, p90 32.2s
- `deploy` job: median 9.0s, p90 10.0s
Measured `build` step timings across the inspected successful runs:
- `Restore node_modules`: median 6.0s, p90 7.0s
- `Build documentation`: median 5.0s, p90 6.0s
- `Restore dashboard from cache`: median 0.0s, p90 1.0s
- `Mount dashboard at /cao`: median 2.0s, p90 2.1s
- `Upload Pages artifact`: median 4.0s, p90 4.0s
Cache verification from Actions metadata and step outcomes:
- `Install dependencies` was skipped in every inspected successful run because `steps.node-modules-cache.outputs.cache-hit == 'true'`.
- `Save node_modules` was also skipped in every inspected successful run.
- This shows the separate `node_modules` cache is consistently hitting, but also that no comparable successful run in the sample needed a fresh install.
Confidence: medium-high for the dependency path because the result is repeated across recent successful runs on multiple SHAs and both `schedule` and `push` triggers.
Relevant source locations:
- `.github/workflows/docs.yml` `build` job steps `Set up Node.js`, `Restore node_modules`, `Install dependencies`, and `Save node_modules`
- `.github/workflows/dashboard-build.yml` for the dispatched dashboard artifact/cache path used by the same workflow family
References:
- `https://github.com/githubnext/gh-aw-cao/actions/runs/34195454259`
- `https://github.com/githubnext/gh-aw-cao/actions/runs/34194868768`
- `https://github.com/githubnext/gh-aw-cao/actions/runs/34192990125`
- `https://github.com/githubnext/gh-aw-cao/actions/runs/34192616762`
- `https://github.com/githubnext/gh-aw-cao/actions/runs/34192480725`
### Bottleneck
The current `build` job pays for two dependency-cache layers:
1. `actions/setup-node` with `cache: npm`, which already restores the npm package cache keyed by `package-lock.json`; and
2. a second full-directory cache restore for `node_modules`.
In the observed runs, the second layer no longer avoids any `npm ci` work because installation never runs, yet the restore itself still costs about as much as `npm run docs:build` (median 6s vs. 5s). That means roughly 6% of total median workflow execution time is recurring cache-management overhead with no demonstrated savings in the recent sample.
### Recommended changes
Simplify dependency handling in `.github/workflows/docs.yml` by removing the explicit `node_modules` restore/save pair and always running `npm ci` after `actions/setup-node` restores the npm cache.
Concretely:
- keep `actions/setup-node` with `cache: npm`;
- delete `Restore node_modules` and `Save node_modules`;
- replace the conditional install with unconditional `npm ci`.
Why this is the best current category improvement:
- It removes a repeated 6s median cost that shows up on every successful build.
- It reduces cache fragility from persisting a full `node_modules` tree across runs and runner images.
- It keeps correctness and freshness intact because `npm ci` remains the lockfile-authoritative install path.
### Expected effect and validation
Expected effect: save roughly 6 seconds per successful docs build immediately, with larger savings possible by avoiding occasional stale-tree edge cases. On the current median of 93.5s, that is about 6.4% faster end-to-end. This does not meet the 60-second / 15% threshold alone, so validate it together with any future dashboard-side optimization rather than treating it as a complete solution.
Validation plan:
1. Ship the workflow change on `main`.
2. Compare at least five `push` runs and five `schedule` runs before/after on the same workflow shape.
3. Confirm the `build` job no longer includes the `Restore node_modules` step and that `npm ci` duration plus `setup-node` duration is lower than the removed cache-restore overhead in aggregate.
4. Confirm no regression in lockfile fidelity, Pages contents, or dashboard mounting.
### Caveats
- The recent evidence window did not include a successful run where the `node_modules` cache missed, so this recommendation optimizes the current steady state rather than a cold-cache scenario.
- The largest remaining visible contributor is still the externalized `dashboard` job at ~45 seconds median, so this recommendation is a safe incremental win, not the final build-time fix.
- Queue time was low in the inspected sample and was separated conceptually from execution time; the recommendation targets execution time only.
### Control Plane
- Correlation ID: `34195155197-388`
- Central repository: `githubnext/gh-aw-cao`
- Control plane run: `https://github.com/githubnext/gh-aw-cao/actions/runs/34195155197`
### References
- Workflow source: `.github/workflows/docs.yml`
- Dispatched workflow source: `.github/workflows/dashboard-build.yml`
- Actions runs: `34195454259`, `34194868768`, `34192990125`, `34192616762`, `34192480725`, `34192397470`, `34191999856`, `34191890934`, `34191085336`, `34190459618`
> Generated by [SelfCare / Docs Build Time](https://github.com/githubnext/gh-aw-cao/actions/runs/34195481946) · pi · gpt54 · 29.6 AIC · ⌖ 8.52 AIC · ⊞ 8.8K · [◷](https://github.com/search?q=repo%3Agithubnext%2Fgh-aw-cao+is%3Aissue+%22gh-aw-workflow-call-id%3A+githubnext%2Fgh-aw-cao%2Fself-care-docs-build-time-investigator%22&type=issues)
> - [x] expires on Sep 22, 2026, 6:43 AM UTC
Contributor guide
Research direction
Start in .github/workflows/docs.yml and inspect the build job steps Set up Node.js, Restore node_modules, Install dependencies, and Save node_modules; compare the related path in .github/workflows/dashboard-build.yml. Apply the requested workflow simplification, then compare five push and five schedule runs with the prior workflow shape. Done means the extra restore step is absent, npm ci runs, and Pages contents and dashboard mounting show no regression.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github-actions, node.js
- Domain
- ci-cd, performance
- Issue type
- Refactor
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 84/100