githubnext / githubnext/gh-aw-cao

[self-care:docs-build-time-investigator] Simplify docs build dependency caching by dropping the extra node_modules cache

Closed Beginner friendly
#3,828 0 comments 0 reactions 0 assignees View on GitHub
self-care self-care:docs-build-time-investigator
Dominant language
JavaScript
Stars
3
Forks
1
Avg merge
49m
Merged PRs (30d)
837

Description

### Summary
The current `docs.yml` build spends a repeatable 9–13 seconds per run on redundant Node dependency cache work in the `build` job, even though `npm ci` almost never runs. Across 15 successful Documentation Pages runs from 2026-09-06 17:08 UTC through 20:22 UTC, the full workflow median was 88s (p90 139s), and the `build` job median was 27s (p90 32s). The evidence supports removing the explicit `node_modules` cache restore/save pair and relying on `actions/setup-node`'s built-in npm cache instead.

### Timing evidence
- Evidence window: 2026-09-06 17:08 UTC to 2026-09-06 20:22 UTC.
- Comparable successful `docs.yml` runs analyzed: 15 (mix of `schedule` and `push`; cancelled runs excluded).
- Failed/outlier runs disclosed but excluded from the comparable sample: 4 failed runs in the same 20-run window; 2 successful runs had large queue delays before `dashboard` started (67s and 88s) but normal execution times, so they were kept for execution metrics and separated from queue time.
- Workflow duration: median 88s, p90 139s.
- Queue before `dashboard`: median 4s, p90 42s.
- `dashboard` job execution: median 39s, p90 43s.
- `build` job execution: median 27s, p90 32s.
- `deploy` job execution: median 10s, p90 10s.
- Repeated `build`-job step timings from trusted Actions metadata:
- `Set up Node.js`: median 6s, p90 7s.
- `Restore node_modules`: median 5s, p90 7.6s.
- `Build documentation`: median 5s, p90 6s.
- `Upload Pages artifact`: median 3s, p90 3s.
- In all 15 successful sampled runs, `Install dependencies` and `Save node_modules` were skipped, which is direct evidence that the explicit `node_modules` cache was already warm and only paying restore overhead.

### Bottleneck
`docs.yml` currently layers two dependency cache mechanisms in the same job:
- `actions/setup-node` with `cache: npm`
- a second explicit `actions/cache` restore/save around `node_modules`

Source locations:
- `.github/workflows/docs.yml` `build` job: `Set up Node.js`, `Restore node_modules`, `Install dependencies`, `Save node_modules`

Because `npm ci` did not run in any successful sample, the explicit `node_modules` cache path contributed recurring restore cost without offsetting install time in this evidence window. That restore step alone consumed about as much time as `npm run docs:build` itself.

### Recommended changes
1. Remove the explicit `Restore node_modules`, conditional `Install dependencies`, and `Save node_modules` steps from `.github/workflows/docs.yml`.
2. Keep `actions/setup-node` with `cache: npm`, then run `npm ci` unconditionally before `npm run docs:build`.
3. Validate on both `push` and `schedule` runs that the npm tarball cache keeps install time bounded and that lockfile changes still invalidate correctly.

This simplifies cache behavior, avoids restoring a large `node_modules` tree on every run, and keeps dependency freshness/correctness aligned with `package-lock.json`.

### Expected effect and validation
- Expected savings: about 5s median and up to 8s on slower runs from eliminating `Restore node_modules` alone, plus simplified cache handling. Relative to the 27s median `build` job, that is about 19%; relative to the 88s median full workflow, it is about 6%.
- Confidence: medium. The step-level evidence is consistent across 15 successful runs, but this recommendation does not yet meet the 60s full-workflow savings bar on its own.
- Validation:
- Compare at least 5 post-change successful runs against the same metrics.
- Confirm `npm ci` duration plus `setup-node` cache behavior is less than the current `Restore node_modules` + skipped-install pattern.
- Check that lockfile changes trigger expected dependency refreshes.

### Caveats
- This recommendation improves caching efficiency and simplifies dependency handling, but based on the current sample it is a modest optimization rather than a major workflow reduction.
- The largest execution component remains the upstream dispatched dashboard build (`dashboard` job median 39s, p90 43s; one 70s outlier), so larger wins will likely come from later suggestion-cycle categories.
- Queue spikes before the `dashboard` job were real but are scheduler capacity effects, not a cache-design issue.

### Control Plane
- Correlation ID: `34057523088-306`
- Central repository: `githubnext/gh-aw-cao`
- Control plane run: https://github.com/githubnext/gh-aw-cao/actions/runs/34057523088

### References
- Workflow source: `.github/workflows/docs.yml`
- Dispatched workflow source: `.github/workflows/dashboard-build.yml`
- Successful evidence runs:
- https://github.com/githubnext/gh-aw-cao/actions/runs/34057733912
- https://github.com/githubnext/gh-aw-cao/actions/runs/34057065990
- https://github.com/githubnext/gh-aw-cao/actions/runs/34056709913
- https://github.com/githubnext/gh-aw-cao/actions/runs/34054791783
- https://github.com/githubnext/gh-aw-cao/actions/runs/34054400780
- https://github.com/githubnext/gh-aw-cao/actions/runs/34053537546
- https://github.com/githubnext/gh-aw-cao/actions/runs/34053435551
- https://github.com/githubnext/gh-aw-cao/actions/runs/34052043769
- https://github.com/githubnext/gh-aw-cao/actions/runs/34051584080
- https://github.com/githubnext/gh-aw-cao/actions/runs/34050415641
- https://github.com/githubnext/gh-aw-cao/actions/runs/34049612967
- https://github.com/githubnext/gh-aw-cao/actions/runs/34048842877
- https://github.com/githubnext/gh-aw-cao/actions/runs/34048835789
- https://github.com/githubnext/gh-aw-cao/actions/runs/34048155331
- https://github.com/githubnext/gh-aw-cao/actions/runs/34047669790

> Generated by [SelfCare / Docs Build Time](https://github.com/githubnext/gh-aw-cao/actions/runs/34057699557) · pi · gpt54 · 44.3 AIC · ⌖ 8.51 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 20, 2026, 8:27 PM UTC

Contributor guide

Open the contributing guide

Research direction

Start with the build job in .github/workflows/docs.yml, focusing on Set up Node.js, Restore node_modules, Install dependencies, and Save node_modules. Compare the workflow before and after the cache simplification, then validate at least five successful push and schedule runs, including lockfile-change behavior and build timing.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions, javascript, nodejs
Domain
build-system, ci-cd, performance
Issue type
Refactor
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
78/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.