githubnext / githubnext/gh-aw-cao

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

Closed Beginner friendly
#5,405 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 docs Pages workflow is already fast overall, but it consistently spends about 6–9 seconds restoring a 436 MB `node_modules` cache before every build while `astro build` itself takes only about 3.5 seconds. Replacing the explicit `node_modules` cache with the existing npm package cache and always running `npm ci` is the clearest build-time win in the current evidence window.

### Timing evidence
Evidence window: latest 20 completed `docs.yml` runs in the last 14 days (2026-09-07T22:30Z to 2026-09-08T03:28Z). Sample: 20 successful comparable runs, including 16 scheduled and 4 push-triggered runs; cancelled runs: 0; failures in window: 0.

Observed workflow timing from trusted Actions metadata:
- Full workflow median: 92.5s; p90: 105.5s.
- `dashboard` job median: 44.0s; p90: 48.2s.
- `build` job median: 26.0s; p90: 33.0s.
- `deploy` job median: 10.0s; p90: 11.0s.
- Queue time was negligible in sampled runs because `createdAt` and `startedAt` were effectively identical.

Repeated build-step timing from run `34183554096` is representative of the steady state:
- `Restore node_modules`: 6s in job metadata, with 457,080,557 bytes restored from cache key `Linux-node-24-a527ea1a3587...`.
- `Build documentation`: 4s in job metadata; Astro reported `29 page(s) built in 3.49s`.
- `Restore dashboard from cache`: 1s, then cache miss.
- `Mount dashboard at /cao`: 1s.
- `Upload Pages artifact`: 3s, uploading 17,986,039 bytes.

Additional comparable runs show the same pattern:
- Run `34170287839`: `Restore node_modules` 8s, `Build documentation` 5s.
- Run `34168576193`: `Restore node_modules` 9s, `Build documentation` 5s.

Relevant workflow sources:
- `.github/workflows/docs.yml`
- `.github/workflows/dashboard-build.yml`

### Bottleneck
The current dependency strategy restores both the built-in npm package cache from `actions/setup-node` and a second explicit `node_modules` cache. In the sampled successful runs, the `node_modules` restore unpacks ~436 MB every time even though the docs build itself is small. That means dependency restore is consistently slower than the actual Astro build, and it consumes about 23% of median `build` job time and about 6–10% of median end-to-end workflow time by itself.

Because the lockfile is already stable across many like-for-like runs, this is repeated overhead rather than an occasional cold-start cost. The dashboard path is not the dominant cost in this category; the dashboard reusable workflow usually completes in ~21s and is separately governed by activity cache behavior.

### Recommended changes
In `.github/workflows/docs.yml`:
1. Remove the explicit `Restore node_modules` and `Save node_modules` steps.
2. Keep `actions/setup-node` with `cache: npm`.
3. Run `npm ci` unconditionally before `npm run docs:build`.

Why this change is evidence-backed:
- The workflow already restores the npm package cache via `actions/setup-node`, so package tarballs can still come from cache.
- The current `node_modules` restore repeatedly transfers and extracts 436 MB.
- The docs output is small and the dependency tree appears stable, so reinstalling from the npm cache is likely cheaper and more predictable than rehydrating the whole installed tree.

### Expected effect and validation
Expected effect: save roughly 6–9 seconds per successful docs build, which is about 23–35% of the median `build` job time and around 7–10% of median end-to-end workflow time in the sampled window.

Validation plan:
1. Land the workflow-only change.
2. Compare at least five post-change successful runs with the same trigger mix.
3. Confirm median `build` job time drops below 20 seconds and that `npm ci` plus `docs:build` together beat the previous `Restore node_modules` + `docs:build` combination.
4. Watch for correctness regressions in `npm run docs:build` output and Pages deployment success.

Confidence: medium. The current evidence clearly shows repeated restore overhead and stable warm-cache behavior. Exact savings from npm-tarball reuse versus full `node_modules` reuse need post-change confirmation.

### Caveats
- This recommendation is specific to the current category: dependency installation and caching.
- The measurable savings are meaningful but do not meet the 60-second threshold on their own; they do meet the alternative 15% threshold for the median `build` job.
- The sampled runs show no queueing problem and no repeated deployment bottleneck.
- `Restore dashboard from cache` misses in representative docs runs because the reusable dashboard workflow saves a run-scoped key; that is worth revisiting under the separate reusable dashboard generation category, not by conflating categories here.

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

### References
- `docs.yml` runs: `34183554096`, `34182088828`, `34181336636`, `34180722668`, `34179614738`, `34178389127`, `34177615363`, `34176646106`, `34175059360`, `34172111197`, `34171800698`, `34171386201`, `34171126691`, `34170630907`, `34170287839`, `34169711859`, `34168651766`, `34168576193`, `34167772638`, `34166921177`
- Representative docs run links:
- https://github.com/githubnext/gh-aw-cao/actions/runs/34183554096
- https://github.com/githubnext/gh-aw-cao/actions/runs/34170287839
- https://github.com/githubnext/gh-aw-cao/actions/runs/34168576193
- Representative reusable dashboard runs:
- https://github.com/githubnext/gh-aw-cao/actions/runs/34183564536
- https://github.com/githubnext/gh-aw-cao/actions/runs/34168703931

> Generated by [SelfCare / Docs Build Time](https://github.com/githubnext/gh-aw-cao/actions/runs/34183552338) · pi · gpt54 · 46.4 AIC · ⌖ 8.49 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, 3:33 AM UTC

Contributor guide

Open the contributing guide

Research direction

Start with .github/workflows/docs.yml and compare its setup-node, node_modules cache, npm ci, and docs:build steps; consult .github/workflows/dashboard-build.yml only for surrounding workflow context. Remove the explicit node_modules cache path, keep the npm package cache, and validate at least five successful runs by checking npm ci, docs:build, and Pages deployment timing and correctness.

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
85/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.