githubnext / githubnext/gh-aw-cao

[self-care:docs-build-time-investigator] Drop the redundant node_modules cache from Documentation Pages builds

Closed Beginner friendly
#6,462 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
Replace the explicit `node_modules` cache in `.github/workflows/docs.yml` with the existing `actions/setup-node` npm cache only. Across 15 successful `docs.yml` runs from 2026-09-08 19:46 UTC to 21:32 UTC, the build job already spends a median 7s restoring `node_modules`, while the only observed cold run spent about 19s on `Restore node_modules` + `npm ci` + `Save node_modules`. The current extra cache adds steady overhead every run without evidence of enough savings to justify it.

### Timing evidence
- Evidence window: 2026-09-08 19:46 UTC to 2026-09-08 21:32 UTC
- Comparable successful `docs.yml` runs analyzed: 15
- Triggers represented: 8 `schedule`, 7 `push`
- Excluded from timing baseline: 5 failed runs in the same 20-run window
- Queue time: median 0s, p90 0s
- Full workflow execution: median 103s, p90 154s
- `dashboard` job: median 45s, p90 52s
- `build` job: median 31s, p90 42s
- `deploy` job: median 10s, p90 11s
- `build` step medians from job metadata:
- `Restore node_modules`: ~7s typical (0 cache misses in 14 of 15 successful runs; one miss)
- `Build documentation`: ~7s
- `Mount dashboard at /cao`: ~2s
- `Upload Pages artifact`: ~4s
- Only one successful run in the sample actually missed the explicit `node_modules` cache: `34271539388`. In that run, `Restore node_modules` + `Install dependencies` + `Save node_modules` took about 19s total before docs build.

### Bottleneck
The dominant repeated cost in `build` is not Astro generation itself; it is the unconditional restore of a large `node_modules` cache that costs several seconds on nearly every run. Because `actions/setup-node` is already configured with `cache: npm`, the workflow already has a package-manager cache path designed for repeatable `npm ci` installs. The additional whole-`node_modules` cache duplicates that responsibility and pays restore overhead on every run.

### Recommended changes
In `.github/workflows/docs.yml`:
- remove the `Restore node_modules` and `Save node_modules` steps;
- run `npm ci` unconditionally after `actions/setup-node`;
- keep `actions/setup-node` with `cache: npm` as the sole dependency cache.

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

### Expected effect and validation
Expected effect: eliminate about 6-10 seconds of restore overhead from nearly every successful run, while keeping cold-start dependency installation bounded by the npm tarball cache. Based on the current median full runtime of 103s, that is likely a 6-10% improvement by itself.

Validation plan:
1. Land the workflow change without altering the dashboard or Pages steps.
2. Compare at least 10 post-change successful runs with the same trigger mix.
3. Confirm `build` job median drops by at least 6s and full workflow median drops measurably.
4. Confirm no increase in dependency-related failures and no regression in deployment correctness.

### Caveats
- This recommendation is medium confidence, not high confidence, because the sample window contains only one cold `node_modules` miss and the dashboard subworkflow dominates total runtime in outlier cases.
- The observed evidence supports removing duplicated caching overhead, but does not meet the 60-second savings threshold by itself.
- Failed runs were disclosed and excluded from the success baseline rather than treated as normal samples.

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

### References
- Workflow source: `.github/workflows/docs.yml`
- Reusable workflow source: `.github/workflows/dashboard-build.yml`
- Successful sample runs:
- https://github.com/githubnext/gh-aw-cao/actions/runs/34281028959
- https://github.com/githubnext/gh-aw-cao/actions/runs/34279913550
- https://github.com/githubnext/gh-aw-cao/actions/runs/34279740118
- https://github.com/githubnext/gh-aw-cao/actions/runs/34274416520
- https://github.com/githubnext/gh-aw-cao/actions/runs/34271539388
- Failed/outlier runs disclosed:
- https://github.com/githubnext/gh-aw-cao/actions/runs/34277010801
- https://github.com/githubnext/gh-aw-cao/actions/runs/34276991561
- https://github.com/githubnext/gh-aw-cao/actions/runs/34276698304
- https://github.com/githubnext/gh-aw-cao/actions/runs/34276222488
- https://github.com/githubnext/gh-aw-cao/actions/runs/34276218719

> Generated by [SelfCare / Docs Build Time](https://github.com/githubnext/gh-aw-cao/actions/runs/34281118365) · pi · gpt54 · 32.4 AIC · ⌖ 8.44 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, 9:39 PM UTC

Contributor guide

Open the contributing guide

Research direction

Read the build job in .github/workflows/docs.yml, especially Set up Node.js, Restore node_modules, Install dependencies, and Save node_modules. Remove the redundant cache steps, keep setup-node's npm cache, and run npm ci unconditionally. Validate with at least 10 successful post-change runs, checking build and full-workflow timing, dependency failures, and deployment correctness.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions, javascript, nodejs
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.