githubnext / githubnext/gh-aw-cao
[self-care:docs-build-time-investigator] Remove the redundant node_modules cache from Documentation Pages
- Dominant language
- JavaScript
- Stars
- 3
- Forks
- 1
- Avg merge
- 49m
- Merged PRs (30d)
- 837
Description
### Summary
The docs workflow is already hitting both the npm package cache and the `node_modules` cache, but restoring the extra `node_modules` archive still consumes about 4–8 seconds in every successful `build` job while `npm run docs:build` itself takes only about 4–6 seconds. Removing the explicit `node_modules` restore/save layer from `.github/workflows/docs.yml` is the clearest evidence-backed speedup in the current category.
### Timing evidence
- Evidence window: latest 20 completed `docs.yml` runs in the last 14 days, filtered to 12 comparable successful runs on 2026-09-05 (5 `schedule`, 7 `push`); 4 failed scheduled runs were excluded from the timing baseline and are disclosed below.
- Full workflow duration: median 89s, p90 94s, with queue median 4s and execution dominated by the dashboard dispatch/build path plus docs build/deploy.
- `docs.yml` job durations across the 12 successful runs:
- `dashboard`: median 37s, p90 39s
- `build`: median 28s, p90 32s
- `deploy`: median 9.5s, p90 10s
- In the `build` job, successful logs consistently show:
- `Set up Node.js` npm cache hit
- `Restore node_modules` cache hit for a ~402 MB archive
- `Restore node_modules` takes about 4–8s wall time including download and untar (example run `33962195448`: 5s from 11:02:22 to 11:02:27; run `33960856150`: 8s from 10:31:41 to 10:31:49)
- `Build documentation` takes about 4–6s wall time, with Astro reporting 28 pages built in 3.76s in run `33962195448`
- This means the explicit `node_modules` archive restore is often as expensive as, or more expensive than, the documentation build it is intended to accelerate.
- Confidence: medium-high for this category because the cache-hit behavior is directly visible in trusted Actions metadata/logs across 12 successful runs, and the same pattern appears in both `push` and `schedule` runs.
### Bottleneck
The redundant cache layer in `.github/workflows/docs.yml` is the repeated cost:
- `actions/setup-node` with `cache: npm` already restores the npm package cache.
- The workflow then restores a second cache for `node_modules` keyed by the same lockfile.
- On cache hits, GitHub still downloads and extracts a ~402 MB tarball before the docs build can start.
- Because `npm ci` is skipped on all sampled successful runs, the current steady-state cost is not dependency installation; it is the transfer and extraction of the extra cache.
### Recommended changes
In `.github/workflows/docs.yml`:
1. Remove the `Restore node_modules`, conditional `Install dependencies`, and `Save node_modules` steps.
2. Keep `actions/setup-node` with `cache: npm`.
3. Replace the conditional install logic with a single `npm ci` step after setup-node.
Why this is the recommended direction:
- `npm ci` on a warm npm package cache avoids the 402 MB `node_modules` artifact transfer.
- It simplifies the workflow and removes a cache layer that is visibly expensive even on hits.
- The recommendation stays within correctness and freshness expectations because `npm ci` still produces a clean install from `package-lock.json`.
### Expected effect and validation
- Expected effect: save roughly 4–8s from the median 28s `build` job, which is about 14–29% of that job’s current median runtime. This is below 60s end-to-end, but exceeds the 15% threshold for the job segment being optimized and is the strongest non-duplicate improvement supported by the current category evidence.
- Validation plan:
1. Land the workflow change.
2. Compare at least five successful `docs.yml` runs with the same trigger mix before and after the change.
3. Confirm `build` median drops materially while `npm ci` remains stable and no dependency-resolution regressions appear.
4. Re-check queue time separately so scheduler noise is not credited to the change.
### Caveats
- This recommendation is limited to the current suggestion category: dependency installation and caching.
- It does not claim that the docs workflow’s largest absolute cost is dependency installation; the dashboard path remains the biggest contributor to total execution time.
- Four recent scheduled `docs.yml` runs failed (`33961536424`, `33958860090`, plus newer failed runs not used in the success baseline). They were excluded from the comparable timing baseline and should be reviewed separately, but they do not change the repeated cache-hit cost observed in successful runs.
- If maintainers know `npm ci` on a warm npm cache is slower than the current 402 MB restore in practice, they should validate on a branch before rollout; the current repository evidence points the other way.
### Control Plane
- Correlation ID: `33963310924-218`
- Central repository: `githubnext/gh-aw-cao`
- Control plane run: `https://github.com/githubnext/gh-aw-cao/actions/runs/33963310924`
### References
- Workflow source: `.github/workflows/docs.yml`
- Reusable workflow source: `.github/workflows/dashboard-build.yml`
- Successful evidence runs:
- `https://github.com/githubnext/gh-aw-cao/actions/runs/33962974688`
- `https://github.com/githubnext/gh-aw-cao/actions/runs/33962195448`
- `https://github.com/githubnext/gh-aw-cao/actions/runs/33960856150`
- `https://github.com/githubnext/gh-aw-cao/actions/runs/33960380055`
- `https://github.com/githubnext/gh-aw-cao/actions/runs/33959540500`
- `https://github.com/githubnext/gh-aw-cao/actions/runs/33963049755`
- `https://github.com/githubnext/gh-aw-cao/actions/runs/33963039886`
- `https://github.com/githubnext/gh-aw-cao/actions/runs/33962501091`
- `https://github.com/githubnext/gh-aw-cao/actions/runs/33960610830`
- `https://github.com/githubnext/gh-aw-cao/actions/runs/33960445719`
- `https://github.com/githubnext/gh-aw-cao/actions/runs/33959736700`
- `https://github.com/githubnext/gh-aw-cao/actions/runs/33959683227`
- Example cache-hit evidence in `docs.yml` build log: run `33962195448`, job `build`
- Example artifact/cache evidence in `dashboard-build.yml` build log: run `33962980665`, job `build`
> Generated by [SelfCare / Docs Build Time](https://github.com/githubnext/gh-aw-cao/actions/runs/33963465573) · pi · gpt54 · 57.8 AIC · ⌖ 8.52 AIC · ⊞ 8.7K · [◷](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 19, 2026, 11:37 AM UTC
Contributor guide
Research direction
Open .github/workflows/docs.yml and inspect the build job, especially the setup-node, node_modules cache, conditional install, and save steps. Remove the redundant cache layer, retain npm caching, and use the specified clean install step. Validate with at least five successful docs.yml runs, comparing build duration and checking for dependency-resolution regressions.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github-actions, javascript, node.js
- Domain
- build-system, ci-cd, documentation
- Issue type
- Refactor
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 82/100