githubnext / githubnext/gh-aw-cao

[self-care:docs-build-time-investigator] Remove duplicate node dependency cache restores from Documentation Pages

Closed Beginner friendly
#2,297 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 Documentation Pages workflow is spending a large share of its median runtime restoring two overlapping dependency caches even when no install is needed. Across 20 successful `docs.yml` runs from the last 14 days, the full workflow median was 83.5s (p90 94.6s) and the build job median was 23.0s (p90 29.2s). Within that build job, `actions/setup-node` cache restore took a median 4.0s and the explicit `Restore node_modules` step took another median 4.0s, while `Install dependencies` was effectively skipped in the sampled successful runs. This makes dependency cache restore the largest repeated cost inside the docs build job after the actual docs build itself.

### Timing evidence
- Evidence window: latest 20 completed, non-cancelled `docs.yml` runs from 2026-09-05 01:34 UTC to 2026-09-05 04:46 UTC.
- Comparable successful samples: 20/20.
- Excluded from timing baseline: cancelled runs none; dashboard-build failures were disclosed but not used as successful docs baselines.
- Workflow timings:
- Full workflow median 83.5s; p90 94.6s.
- Queue time median 4.0s; p90 4.1s.
- Execution time median 79.0s; p90 88.1s.
- `docs.yml` job timings:
- `dashboard` median 37.0s; p90 42.0s.
- `build` median 23.0s; p90 29.2s.
- `deploy` median 9.0s; p90 11.0s.
- `build` step timings:
- `Set up Node.js` median 4.0s; p90 6.0s.
- `Restore node_modules` median 4.0s; p90 7.0s.
- `Build documentation` median 5.0s; p90 5.1s.
- `Upload Pages artifact` median 2.0s; p90 2.1s.
- Cache-hit verification from logs:
- Run `33945440467`: `Cache hit for: node-cache-...` and `Cache hit for: Linux-node-24-...`; `Install dependencies` did not run.
- Run `33944914195`: same double cache hit pattern.
- Run `33943458856`: same double cache hit pattern with 438 MB npm cache and 421 MB `node_modules` cache restoration messages.
- Like-for-like checks on repeated SHAs show stable totals, so this repeated restore cost is not explained by source variance alone.

### Bottleneck
`docs.yml` currently restores both the built-in npm package cache from `actions/setup-node` and a separate full `node_modules` cache keyed by the same `package-lock.json` hash:
- `.github/workflows/docs.yml`: `Set up Node.js` with `cache: npm`
- `.github/workflows/docs.yml`: `Restore node_modules`, conditional `Install dependencies`, and `Save node_modules`

In the sampled successful runs, the `node_modules` cache hit every time inspected, so the workflow repeatedly pays for downloading and unpacking a second large cache even though `npm ci` is not needed. Those two restore steps together consume about 8 seconds median, roughly 35% of the `build` job and about 10% of total workflow execution time.

### Recommended changes
In `.github/workflows/docs.yml`, remove the explicit `Restore node_modules` / conditional `Install dependencies` / `Save node_modules` pattern and instead always run `npm ci` after `actions/setup-node` with `cache: npm`.

Proposed workflow shape:
- keep `actions/setup-node` with `node-version: 24` and `cache: npm`
- delete the explicit `actions/cache/restore` and `actions/cache/save` steps for `node_modules`
- run `npm ci` unconditionally before `npm run docs:build`

Why this is the better caching posture here:
- it uses one cache layer instead of two overlapping ones
- it avoids restoring a 400+ MB `node_modules` archive on every run
- it keeps installs deterministic from the lockfile
- it aligns with the documented recommendation to cache the package manager data, not `node_modules`, for npm-based CI jobs

### Expected effect and validation
Expected effect: save about 4-8 seconds from median `build` job time and about 5-10% from end-to-end workflow time in the current steady state, with stronger determinism and less cache churn. Confidence is medium: the timing evidence clearly shows duplicate cache restore overhead, but the exact net gain depends on how fast `npm ci` runs with a warm npm cache on GitHub-hosted runners.

Validation plan:
1. Land the workflow change only in `docs.yml`.
2. Compare at least five post-change successful runs on the same trigger mix.
3. Confirm from logs that only the npm cache is restored.
4. Recompute medians for the `build` job and the `Set up Node.js` + install segment.
5. Accept the change if the median build job time drops without introducing flaky installs or stale dependency behavior.

### Caveats
- This recommendation is evidence-backed and safe, but it does not meet the stricter 60-second or 15% total-runtime improvement threshold on current data. It is the clearest concrete caching improvement available in the current category.
- The dominant end-to-end cost remains the separate dashboard workflow plus downstream handoff, not Astro docs generation.
- Two failed `dashboard-build.yml` runs appeared in the surrounding time window (`33940824310`, `33940760241`), but they were not part of the successful docs timing baseline and do not affect the cache finding above.

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

### References
- Workflow source: `.github/workflows/docs.yml`
- Reusable workflow source: `.github/workflows/dashboard-build.yml`
- Example docs runs:
- https://github.com/githubnext/gh-aw-cao/actions/runs/33945440467
- https://github.com/githubnext/gh-aw-cao/actions/runs/33944914195
- https://github.com/githubnext/gh-aw-cao/actions/runs/33943458856
- Example dispatched dashboard runs:
- https://github.com/githubnext/gh-aw-cao/actions/runs/33945470596
- https://github.com/githubnext/gh-aw-cao/actions/runs/33944919186
- https://github.com/githubnext/gh-aw-cao/actions/runs/33943464432

> Generated by [SelfCare / Docs Build Time](https://github.com/githubnext/gh-aw-cao/actions/runs/33945559170) · pi · gpt54 · 27.6 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, 4:56 AM UTC

Contributor guide

Open the contributing guide

Research direction

Start with .github/workflows/docs.yml and inspect the build job's setup-node, node_modules cache, install, and documentation build steps. Compare the workflow with the proposed single npm cache approach, then validate at least five successful runs by checking logs for one cache restore, successful dependency installation, and unchanged documentation output.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.