githubnext / githubnext/gh-aw-cao

[self-care:docs-build-time-investigator] Remove the unused dashboard cache hop from Documentation Pages handoff

Closed
#5,141 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 current docs deployment spends a repeatable ~9-13 seconds transferring the dashboard build between workflows, but the intended cache handoff never hits. In 11 successful `docs.yml` runs from the last 14 days, every `build` job missed `cao-dashboard--` and fell back to downloading the `central-agentic-ops-dashboard` artifact. Replacing that cache-then-artifact fallback with a direct artifact download path would remove one unused cache round trip and simplify the cross-workflow handoff without changing output freshness or deployment safety.

**Action:** A maintainer should update `.github/workflows/docs.yml` and `.github/workflows/dashboard-build.yml` to use a single artifact-based handoff for the dashboard payload, then confirm that at least 5 consecutive successful `docs.yml` runs show the dashboard handoff step median drop by >=1s with no missing dashboard content in Pages deploys.

### Timing evidence
Evidence window: latest 20 completed `docs.yml` runs, last 14 days; comparable successful sample size: 11 runs (10 schedule, 1 push). Cancelled and failed runs were excluded from baseline timing and are noted as outliers.

Measured medians / p90:
- Full `docs.yml` workflow: 101s median, 140s p90
- `dashboard` job in `docs.yml`: 46s median, 51s p90
- `build` job in `docs.yml`: 31s median, 34s p90
- `deploy` job in `docs.yml`: 10s median, 10s p90
- `build` job in `dashboard-build.yml`: 23s median, 26s p90

Repeated transfer costs inside successful runs:
- `Restore dashboard from cache` in `docs.yml`: always attempted, but every sampled run logged `Cache not found for input keys: cao-dashboard--1`
- `Mount dashboard at /cao` artifact download after cache miss: 1-3s per run
- `Cache dashboard artifact for the dispatching workflow` in `dashboard-build.yml`: 1-2s step duration plus 0.7-1.3s tar/upload time in logs
- `Upload dashboard artifact`: ~2.1-3.0s blob upload for ~10.4-10.6 MB
- `Upload dashboard data artifact`: ~1.6-2.8s blob upload for ~10.0-10.1 MB
- Pages packaging / upload: ~2.3-3.6s for ~11.4-11.5 MB

Confidence: medium-high. The transfer pattern was identical in all 11 comparable successes across multiple source SHAs.

### Bottleneck
The cross-workflow dashboard handoff currently does three things for one payload:
1. saves the dashboard directory into an Actions cache in `dashboard-build.yml`;
2. uploads the same directory again as an artifact; and
3. in `docs.yml`, tries to restore the cache first even though the key is a unique per-run key from a different workflow run.

Trusted logs show that the cache restore path never succeeds in the sampled window, so its network lookup and fallback logic are pure overhead. The artifact path is already the real transport that completes every successful build.

### Recommended changes
1. In `.github/workflows/docs.yml`, remove the `Restore dashboard from cache` step and make `Mount dashboard at /cao` the single handoff path for the dashboard payload.
2. In `.github/workflows/dashboard-build.yml`, remove `Cache dashboard artifact for the dispatching workflow` unless another consumer depends on it.
3. Keep the existing uploaded dashboard artifact and dashboard data artifact until follow-up evidence shows one of them is unnecessary.

Relevant source locations:
- `.github/workflows/docs.yml`: `Restore dashboard from cache` and `Mount dashboard at /cao`
- `.github/workflows/dashboard-build.yml`: `Cache dashboard artifact for the dispatching workflow` and `Upload dashboard artifact`

### Expected effect and validation
Expected effect:
- save roughly 2-4s in `dashboard-build.yml` by dropping the unused cache save;
- save roughly 1s in `docs.yml` by dropping the always-miss cache restore;
- reduce workflow complexity and eliminate a misleading cache path that currently provides no benefit.

This is below the whole-workflow 60s threshold on its own, but it is comfortably above 15% of the reusable dashboard build job median transfer overhead and is the only evidence-backed optimization in the current category that does not trade away freshness or correctness.

Validation plan:
- compare at least 5 successful runs before and after the change;
- verify `docs.yml` still publishes the dashboard under `/cao` in Pages;
- confirm no dashboard handoff step references `actions/cache` for `cao-dashboard-*`;
- confirm run logs no longer show `Cache not found for input keys: cao-dashboard-*` in `docs.yml`.

### Caveats
- Queue time could not be separated from execution time from the available trusted metadata because the retrieved job objects did not include usable queued timestamps; the recommendation relies on step and job execution timing only.
- Several failures and one cancelled run existed in the 20-run window; they were disclosed but excluded from the success baseline.
- Open-issue duplicate checking was attempted but GitHub issue listing returned an upstream 502 from the available read path, so this recommendation should be treated as best-effort duplicate avoidance rather than a guaranteed no-duplicate result.

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

### References
- `docs.yml` runs: 34166921177, 34166361708, 34166284786, 34165207941, 34164303858, 34163413159, 34159735692, 34159141005, 34157814609, 34156832503, 34155875936
- Example `docs.yml` runs showing repeated dashboard cache misses and artifact download fallback:
- https://github.com/githubnext/gh-aw-cao/actions/runs/34163413159
- https://github.com/githubnext/gh-aw-cao/actions/runs/34159735692
- https://github.com/githubnext/gh-aw-cao/actions/runs/34159141005
- Matching `dashboard-build.yml` runs showing cache save plus artifact upload for the same payload:
- https://github.com/githubnext/gh-aw-cao/actions/runs/34163421635
- https://github.com/githubnext/gh-aw-cao/actions/runs/34159742474
- https://github.com/githubnext/gh-aw-cao/actions/runs/34159151273

> Generated by [SelfCare / Docs Build Time](https://github.com/githubnext/gh-aw-cao/actions/runs/34166942306) · pi · gpt54 · 47.4 AIC · ⌖ 8.51 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 21, 2026, 10:37 PM UTC

Contributor guide

Open the contributing guide

Research direction

Start with the named steps in .github/workflows/docs.yml and .github/workflows/dashboard-build.yml, then inspect the referenced workflow runs and artifact handoff. Confirm the dashboard artifact still mounts at /cao and Pages output remains complete. Done means five successful docs.yml runs show no cao-dashboard cache lookup and the handoff timing improves without missing dashboard content.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions
Domain
ci-cd, devops
Issue type
Refactor
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.