githubnext / githubnext/gh-aw-cao
[self-care:docs-build-time-investigator] Remove the duplicate node_modules cache restore from Documentation Pages builds
- Dominant language
- JavaScript
- Stars
- 3
- Forks
- 1
- Avg merge
- 49m
- Merged PRs (30d)
- 837
Description
### Summary
The Documentation Pages workflow spends a repeatable chunk of its execution rehydrating two large dependency caches on every successful run even though `npm ci` is skipped. Across 10 comparable successful runs from 2026-09-04 15:23 UTC to 16:33 UTC, the `build` job’s median execution time was 27s and the combined dependency-cache restore time inside that job was 9.5s median. The evidence shows `actions/setup-node` restores the npm cache (~414 MB) and the separate `node_modules` cache restore then downloads another ~398 MB, making dependency rehydration roughly 35% of the median `build` job.
### Timing evidence
- Evidence window: 2026-09-04T15:23:15Z to 2026-09-04T16:33:15Z
- Comparable successful `docs.yml` runs analyzed: 10
- Triggers represented: 6 `schedule`, 4 `push`
- Excluded from timing baseline: 1 cancelled `docs.yml` run (`33889175553`)
- Full workflow duration: median 98s, p90 152.6s
- Queue time before first job started: median 4s, p90 69.3s
- `dashboard` job duration: median 38.5s, p90 44.5s
- `build` job duration: median 27s, p90 31.1s
- `deploy` job duration: median 10s, p90 12s
- `Build documentation` step: median 5s, p90 5.1s
- `Restore node_modules` step: median 5.5s, p90 7s
- Trusted cache-hit evidence: every sampled run skipped `Install dependencies`, and sampled logs show both a `setup-node` npm cache hit and a separate `Restore node_modules` cache hit.
### Bottleneck
The current workflow restores two heavyweight dependency caches in the same job:
- `.github/workflows/docs.yml` `build` job uses `actions/setup-node` with `cache: npm`.
- The same job also restores `node_modules` with `actions/cache/restore` keyed by `package-lock.json`.
In run `33895784928`, trusted logs show:
- `actions/setup-node` restored `434353315 B` and finished with `Cache restored from key: node-cache-Linux-x64-npm-...`.
- `Restore node_modules` then restored `417486543 B` and finished with `Cache restored from key: Linux-node-24-...`.
- `Install dependencies` was skipped because `node_modules` was already present.
This means the workflow repeatedly downloads ~851 MB of dependency cache data to avoid a dependency install step that did not run in any sampled successful build. The docs build itself is already fast at ~5s median, so the extra cache restore is the dominant avoidable cost inside the `build` job.
### Recommended changes
1. In `.github/workflows/docs.yml`, remove the explicit `Restore node_modules`, conditional `Install dependencies`, and conditional `Save node_modules` steps.
2. Keep `actions/setup-node` with `cache: npm` enabled.
3. Replace the current conditional dependency logic with a single unconditional `npm ci` before `npm run docs:build`.
Why this is the best next change for the current evidence category:
- It keeps correctness and freshness because dependencies are still installed from `package-lock.json` every run.
- It uses the cache GitHub already manages for npm tarballs instead of restoring a second near-duplicate working tree cache.
- It targets the largest repeated cost that is visible in trusted metadata and logs for this category.
### Expected effect and validation
- Expected effect: save about 4–7s per `docs.yml` `build` job by eliminating the second cache restore, which is about 15–26% of the median 27s `build` job. This is below 60s for the full workflow, but it clears the package threshold via the 15% job-level reduction and removes the biggest repeated execution cost in the investigated category.
- Confidence: medium. The sampled logs prove the duplicate restore cost today, but validating the exact replacement cost requires A/B comparison after the workflow change.
- Validation plan:
1. Compare at least 5 successful runs before and after the change on the same trigger mix.
2. Confirm the new `npm ci` duration plus the single npm cache restore is lower than the old `Restore node_modules` + skipped install path.
3. Recompute median and p90 for the `build` job and verify no regression in `docs:build` output correctness.
### Caveats
- This recommendation targets execution time, not queue time. Queue time has higher variance and drove the longest total runs in two samples.
- The current sample window was dense and recent rather than spread across the full 14-day allowance because the latest 20 completed runs were all from the last ~2 hours.
- I did not find an existing open issue in the sampled repository outputs that clearly duplicates this specific recommendation, but maintainers should still check before implementation if parallel optimization work is underway.
### Control Plane
- Correlation ID: `33895662082-169`
- Central repository: `githubnext/gh-aw-cao`
- Control plane run: https://github.com/githubnext/gh-aw-cao/actions/runs/33895662082
### References
- Workflow source: `.github/workflows/docs.yml`
- Reusable workflow source: `.github/workflows/dashboard-build.yml`
- Sample runs: `33895784928`, `33895035427`, `33895025453`, `33894069320`, `33894017666`, `33892834046`, `33892672055`, `33891345687`, `33890063424`, `33889178648`
- Representative docs workflow run: https://github.com/githubnext/gh-aw-cao/actions/runs/33895784928
- Representative dashboard build run: https://github.com/githubnext/gh-aw-cao/actions/runs/33895797083
> Generated by [SelfCare / Docs Build Time](https://github.com/githubnext/gh-aw-cao/actions/runs/33896141661) · pi · gpt54 · 56.1 AIC · ⌖ 8.47 AIC · ⊞ 8.6K · [◷](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 18, 2026, 4:44 PM UTC
Contributor guide
Research direction
Start in .github/workflows/docs.yml and inspect the build job’s setup-node, Restore node_modules, Install dependencies, Save node_modules, and Build documentation steps. Remove the duplicate node_modules cache path while retaining npm caching and an unconditional npm ci before npm run docs:build. Validate with at least five successful before-and-after runs, comparing build timing and confirming the documentation output remains correct.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github-actions, javascript, node.js
- Domain
- build-system, ci-cd
- Issue type
- Refactor
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 78/100