githubnext / githubnext/gh-aw-cao
[self-care:docs-build-time-investigator] Remove redundant dashboard cache hop from Documentation Pages
- Dominant language
- JavaScript
- Stars
- 3
- Forks
- 1
- Avg merge
- 49m
- Merged PRs (30d)
- 837
Description
### Summary
The documentation-pages workflow is already getting reliable dependency-cache hits, but it still repackages and uploads the same dashboard payload twice on every successful run. Across eight comparable successful scheduled `docs.yml` runs on 2026-09-08, the median full workflow time was 98s (p90 114s), with the top recurring cost inside the critical path coming from the dispatched dashboard build plus two artifact-transfer hops. The clearest improvement is to stop uploading the full dashboard as both an Actions artifact and a cache entry, and instead consume the existing artifact directly once in `docs.yml`.
### Timing evidence
Evidence window: latest 20 completed `docs.yml` runs in the last 14 days, filtered to 8 comparable successful scheduled runs and 3 disclosed failures/outliers.
Comparable successful `docs.yml` runs:
- Full workflow total: median 98s, p90 114s
- Queue time before first job: median 3.5s, p90 14.8s
- Execution time after first job starts: median 94.5s, p90 98.8s
- `dashboard` job: median 44.5s, p90 52.9s
- `build` job: median 27.0s, p90 36.6s
- `deploy` job: median 9.5s, p90 11.3s
Dispatched `dashboard-build.yml` runs paired to those samples:
- `activity` job: typically 4-8s in cache mode
- `build` job: typically 18-25s, with repeated artifact work every run
Observed repeated transfer costs from logs:
- `dashboard-build.yml` uploads `central-agentic-ops-dashboard` in about 3-4s every run
- `docs.yml` then downloads that artifact in about 2-3s every run because the cache key is a fresh per-run key and consistently misses
- `docs.yml` then repackages and uploads the final Pages artifact in about 3-4s every run
Representative runs:
- `docs.yml` 34209983281: https://github.com/githubnext/gh-aw-cao/actions/runs/34209983281
- `docs.yml` 34207779868: https://github.com/githubnext/gh-aw-cao/actions/runs/34207779868
- `docs.yml` 34206549964: https://github.com/githubnext/gh-aw-cao/actions/runs/34206549964
- `dashboard-build.yml` 34209997064: https://github.com/githubnext/gh-aw-cao/actions/runs/34209997064
- `dashboard-build.yml` 34207797320: https://github.com/githubnext/gh-aw-cao/actions/runs/34207797320
Confidence: medium-high. The sample size is modest but consistent, and the cache-hit/miss evidence comes directly from trusted Actions metadata and logs.
### Bottleneck
The current pipeline duplicates large payload transfer for the dashboard:
1. `dashboard-build.yml` saves the generated dashboard directory to an Actions cache with a unique per-run key (`cao-dashboard-${{ github.run_id }}-${{ github.run_attempt }}`) and also uploads the same directory as the `central-agentic-ops-dashboard` artifact.
2. `docs.yml` tries to restore that cache using the dispatched run ID and almost always logs `Cache not found for input keys`, then downloads the artifact anyway.
3. The artifact being downloaded is large enough to matter: run 34209983281 downloaded `central-agentic-ops-dashboard` at 17,036,198 bytes, and the subsequent Pages upload produced a final 18,006,446-byte archive.
Because the cache key is intentionally unique to the dashboard-build run, it does not create reuse across docs runs; it only adds an extra save/restore path around a transfer that is already handled correctly by the artifact.
### Recommended changes
1. In `.github/workflows/dashboard-build.yml`, remove the `Cache dashboard artifact for the dispatching workflow` step.
2. In `.github/workflows/docs.yml`, remove the `Restore dashboard from cache` step and its conditional branching.
3. Always download `central-agentic-ops-dashboard` from the dispatched dashboard-build run in the `Mount dashboard at /cao` step.
4. Keep the existing npm cache and `node_modules` restore behavior unchanged; current logs show dependency installation is already skipped on all sampled successful runs, so that is not the largest remaining cost.
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 effect: save roughly 60s or more per day of scheduled build time at the current 15-minute cadence by removing one unnecessary large cache save and one guaranteed cache miss path on every successful scheduled run, while simplifying the pipeline and reducing transfer variance. Per-run savings are likely modest (roughly 2-5s on the docs side plus 1-2s on the dashboard-build side), so this is an operations-efficiency optimization rather than a single-run latency breakthrough.
Validation plan:
1. Compare at least five like-for-like scheduled runs before and after the change on the same trigger class.
2. Confirm the removed cache step disappears from `dashboard-build.yml` logs.
3. Confirm `docs.yml` no longer emits `Cache not found for input keys: cao-dashboard-...`.
4. Recompute medians/p90 for the `dashboard` and `build` jobs and verify reduced artifact-transfer overhead with no increase in failures or stale dashboard content.
### Caveats
- This recommendation improves repeated transfer efficiency and workflow simplicity, not the already-fast Astro site build itself; `Build documentation` was only about 5-6s at the job level and the Astro build output reported about 3.7s in the sampled logs.
- Queue time remains external variability and should stay separated from execution time.
- Two recent failed `docs.yml` runs (34211843376 and 34210903440) and one earlier failed run (34201029490) were excluded from comparable timing calculations but disclosed in the evidence window.
### Control Plane
- Correlation ID: `34211828979-395`
- Central repository: `githubnext/gh-aw-cao`
- Control plane run: https://github.com/githubnext/gh-aw-cao/actions/runs/34211828979
### References
- `.github/workflows/docs.yml`
- `.github/workflows/dashboard-build.yml`
- `docs.yml` runs: 34209983281, 34207779868, 34206549964, 34204937773, 34202354819, 34200131418, 34199286815, 34197784483
- `dashboard-build.yml` runs: 34209997064, 34207797320, 34206561112, 34204950805, 34202365448, 34200192176, 34199297209, 34197793673
> Generated by [SelfCare / Docs Build Time](https://github.com/githubnext/gh-aw-cao/actions/runs/34212208715) · pi · gpt54 · 48.6 AIC · ⌖ 8.52 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:57 AM UTC
Contributor guide
Research direction
Start in .github/workflows/dashboard-build.yml at “Cache dashboard artifact for the dispatching workflow” and “Upload dashboard artifact”, then inspect the “Restore dashboard from cache” and “Mount dashboard at /cao” steps in .github/workflows/docs.yml. Remove the redundant cache path while preserving the existing artifact download, then compare at least five like-for-like scheduled runs and confirm the cache step and cache-miss log no longer appear without stale content or increased failures.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github-actions
- Domain
- ci-cd
- Issue type
- Refactor
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 78/100