githubnext / githubnext/gh-aw-cao
[self-care:docs-build-time-investigator] Reuse dashboard output across docs runs instead of keying the cache by dispatched run ID
- Dominant language
- JavaScript
- Stars
- 3
- Forks
- 1
- Avg merge
- 49m
- Merged PRs (30d)
- 837
Description
### Summary
The docs workflow is already hitting the npm dependency cache, but it never reuses the dashboard cache because the key is unique per dispatched run. Across 11 comparable successful scheduled runs from 2026-09-06 16:02 UTC to 18:32 UTC, the `dashboard` job median was 38s and the workflow always logged `Cache not found for input keys: cao-dashboard--1`, forcing artifact download every time. Replacing the per-run dashboard cache key with a content-based key and using it directly from `docs.yml` would remove the guaranteed miss and avoid rerunning or redownloading unchanged dashboard output.
### Timing evidence
- Evidence window: latest 11 comparable successful `docs.yml` scheduled runs in the last 14 days, from run `34044157084` to `34052043769`
- Excluded: cancelled run `34044201815`; one failed run `34052745089`; one schedule outlier `34048842877` is disclosed separately below
- Full workflow duration: median 88s, p90 97s, outlier max 176s
- `dashboard` job duration: median 38s, p90 44s
- `build` job duration: median 27s, p90 32s
- `deploy` job duration: median 9s, p90 10s
- Repeated build-step costs in `build`:
- `Set up Node.js`: median 6s, p90 7s
- `Restore node_modules`: median 5s, p90 8s
- `Build documentation`: median 5s, p90 6s
- `Mount dashboard at /cao`: median 1s, p90 2s
- `Upload Pages artifact`: median 3s, p90 3s
- Cache verification from logs:
- `node-cache-...` hit on every sampled successful run
- `Restore dashboard from cache` missed on every sampled successful run with messages such as `Cache not found for input keys: cao-dashboard-34052049662-1`
### Bottleneck
The current dashboard cache is keyed as `cao-dashboard-${{ github.run_id }}-${{ github.run_attempt }}` in `.github/workflows/dashboard-build.yml`, and `docs.yml` restores that exact dispatched-run key via `needs.dashboard.outputs.run-id` and `run-attempt`. That design guarantees a cold cache for every top-level docs run because each dashboard build has a new run ID. As a result, the workflow pays the full dispatched dashboard cost on every run and still falls back to `actions/download-artifact` to mount the dashboard.
### Recommended changes
1. In `.github/workflows/dashboard-build.yml`, replace the saved dashboard cache key with a deterministic content key based on dashboard inputs, for example the workflow SHA plus the activity snapshot identity and dashboard source files.
2. In `.github/workflows/docs.yml`, restore the same deterministic key before attempting `download-artifact`.
3. Keep the artifact upload/download path as fallback for first-build or cache-miss cases, but let unchanged scheduled runs satisfy the dashboard handoff from cache.
4. If the dashboard output is already reproducible for `mode: cache`, consider skipping the dispatch entirely when the deterministic dashboard cache is present.
Relevant source locations:
- `.github/workflows/docs.yml`: `Restore dashboard from cache`, `Mount dashboard at /cao`
- `.github/workflows/dashboard-build.yml`: `Cache dashboard artifact for the dispatching workflow`, `Upload dashboard artifact`
### Expected effect and validation
- Expected savings: about 38s on the median scheduled run if unchanged dashboard output can be restored instead of rebuilt and redownloaded; that is roughly 43% of the 88s median workflow duration, well above the 60s-or-15% action threshold on a p90 basis and clearly above the 15% threshold on the median path.
- Validation plan:
1. Compare at least five like-for-like scheduled runs before and after the change.
2. Confirm `Restore dashboard from cache` shows real hits in `docs.yml` logs.
3. Confirm the `dashboard` stage is skipped or materially shorter without correctness regressions in deployed `/cao` content.
4. Recompute workflow median and p90 to verify the expected drop.
### Caveats
- The cache key must include every input that can change generated dashboard output; otherwise stale dashboard content could be deployed.
- The 176s run `34048842877` appears to be a scheduling/wait outlier because job durations remained normal; it was not used to justify this recommendation.
- This recommendation focuses on the current category only. npm dependency caching already appears healthy in the sampled runs.
### Control Plane
- Correlation ID: `34052696183-302`
- Central repository: `githubnext/gh-aw-cao`
- Control plane run: https://github.com/githubnext/gh-aw-cao/actions/runs/34052696183
### References
- Workflow source: `.github/workflows/docs.yml`
- Workflow source: `.github/workflows/dashboard-build.yml`
- Sample runs:
- 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/34048155331
- https://github.com/githubnext/gh-aw-cao/actions/runs/34047273432
- https://github.com/githubnext/gh-aw-cao/actions/runs/34046489046
- https://github.com/githubnext/gh-aw-cao/actions/runs/34045687761
- https://github.com/githubnext/gh-aw-cao/actions/runs/34045221058
- https://github.com/githubnext/gh-aw-cao/actions/runs/34044157084
> Generated by [SelfCare / Docs Build Time](https://github.com/githubnext/gh-aw-cao/actions/runs/34052925797) · pi · gpt54 · 55.3 AIC · ⌖ 8.48 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, 6:55 PM UTC
Contributor guide
Research direction
Read the `Restore dashboard from cache` and `Mount dashboard at /cao` steps in `.github/workflows/docs.yml`, then compare them with `Cache dashboard artifact for the dispatching workflow` and `Upload dashboard artifact` in `.github/workflows/dashboard-build.yml`. Use the referenced scheduled-run logs to verify the key behavior, then validate that unchanged runs hit the cache, retain artifact fallback, and deploy correct `/cao` content.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github-actions
- Domain
- ci-cd, devops
- Issue type
- Refactor
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100