githubnext / githubnext/gh-aw-cao
[self-care:docs-build-time-investigator] Build the dashboard in-process in docs.yml to remove the cross-workflow artifact round-trip
- Dominant language
- JavaScript
- Stars
- 3
- Forks
- 1
- Avg merge
- 49m
- Merged PRs (30d)
- 837
Description
### Summary
The docs pipeline is already spending very little time on local work: across 12 successful `docs.yml` runs from 2026-09-04T23:27Z to 2026-09-05T01:46Z, median end-to-end time was 85.5s and p90 was 98.8s, while `npm ci` never ran because the `node_modules` cache hit in every successful sample. The biggest remaining repeated cost is the separate dashboard dispatch and cross-run artifact handoff: the `dashboard` job alone medianed 37s inside `docs.yml`, and the dispatched `dashboard-build.yml` workflow medianed another 27s. Two recent scheduled `docs.yml` failures at runs `33935427770` and `33936332934` also came from the dashboard artifact handoff path, including one explicit artifact download rate-limit failure.
### Timing evidence
- Evidence window: 2026-09-04T22:21:00Z to 2026-09-05T01:48:02Z
- Comparable successful `docs.yml` samples: 12 completed runs (`schedule` and `push`), excluding cancelled runs
- Failed/outlier runs disclosed: `33935427770` and `33936332934` failed during the same dashboard handoff path; `33930696456` was a high but still successful outlier at 111s total because `Restore node_modules` took 17s and build job queueing reached 55s
- Full workflow (`docs.yml`): median 85.5s, p90 98.8s
- `dashboard` job in `docs.yml`: median 37.0s, p90 38.9s; queue median 4.0s
- `build` job in `docs.yml`: median 28.5s, p90 33.9s; queue median 44.0s
- `deploy` job in `docs.yml`: median 8.5s, p90 10.0s; queue median 76.0s
- Cached build-step medians inside `docs.yml` build job:
- `Set up Node.js`: 6.0s
- `Restore node_modules`: 5.0s
- `Install dependencies`: 0.0s (skipped in all 12 successful runs)
- `Build documentation`: 5.0s
- `Mount dashboard at /cao`: 2.0s when successful
- `Upload Pages artifact`: 2.0s
- Dispatched `dashboard-build.yml` runs matched to the same 12 samples:
- full reusable workflow median 27.0s, p90 28.9s
- `activity` job median 6.0s, p90 7.0s
- `build` job median 13.0s, p90 14.0s
- dashboard build steps are already small: `Restore collected activity data` median 1.0s, `Assemble Dashboard Language site` median 1.0s, `Build Dashboard Language sources` median 1.0s, `Upload dashboard artifact` median 2.0s
- Like-for-like note: paired `schedule` and `push` runs on the same SHA (`3fddaa5...`, `cba6e3a...`, `cf92730...`, `2051688...`) show similar local build timings, so the persistent extra wall time is structural rather than content-driven.
### Bottleneck
The bottleneck for this category is not dependency installation anymore; it is the overhead and fragility of producing the dashboard in a separate dispatched workflow and then downloading its artifact back into `docs.yml`.
Evidence:
- The docs build itself is cheap (`Build documentation` median 5s) and dependency install is already avoided in every successful sample.
- The `dashboard` dispatch step in `.github/workflows/docs.yml` takes 29-42s in the sampled successes before the docs build can continue.
- The dispatched reusable workflow adds another full workflow run whose work is mostly activity-cache lookup plus artifact upload.
- Failure run `33936332934` failed in `Mount dashboard at /cao` with `Unable to download artifact(s): API rate limit exceeded for installation` after `GET /repos/githubnext/gh-aw-cao/actions/runs/NaN/artifacts?name=central-agentic-ops-dashboard`.
### Recommended changes
Replace the cross-workflow dashboard handoff with an in-process build path inside `docs.yml` so the docs workflow builds or assembles the dashboard directly in the same run workspace instead of dispatching `.github/workflows/dashboard-build.yml` and re-downloading `central-agentic-ops-dashboard`.
Concretely:
- Keep the existing cache-mode activity behavior, but run the dashboard assembly steps now in `.github/workflows/dashboard-build.yml` directly inside `docs.yml` (or extract them into a shared composite action/script invoked by both workflows if you still need a standalone dashboard workflow elsewhere).
- Remove the `dashboard` dispatch job and the `actions/download-artifact` dependency from `.github/workflows/docs.yml` once the local assembly path is in place.
- Preserve correctness by continuing to require the same activity snapshot files and by keeping `mode: cache` as the default for scheduled docs refreshes.
Relevant source locations:
- `.github/workflows/docs.yml`: `dashboard` job dispatches `dashboard-build.yml`; `build` job downloads `central-agentic-ops-dashboard`
- `.github/workflows/dashboard-build.yml`: `build` job already contains the direct dashboard assembly steps that can be reused locally
### Expected effect and validation
Expected effect: removing the extra workflow dispatch plus artifact round-trip should save about 37s from median `docs.yml` wall time, which is ~43% of the current 85.5s median and comfortably above the 60s-or-15% action threshold on p90-adjacent runs when the dispatch path stretches toward 40s and also causes occasional retry/failure pressure.
Validation plan:
1. Run at least five post-change `docs.yml` builds with the same default cache mode.
2. Confirm median full workflow time drops from 85.5s to ≤72s and p90 drops materially.
3. Confirm `actions/download-artifact` is no longer on the critical path.
4. Confirm the produced Pages artifact still contains the dashboard under `/cao` and matches the current content contract.
5. Confirm no new freshness regressions by checking that required activity snapshot files are still enforced before dashboard generation.
Confidence: medium-high, because the cost is repeated across paired push and schedule runs and the failure evidence is directly on the same handoff path.
### Caveats
- Queue time is a large part of total wall time (`build` queue median 44s, `deploy` queue median 76s), and this change will not remove runner-availability delays.
- This recommendation is intentionally limited to the current suggestion category: dependency installation and caching. It is justified here because dependency caching is already effective, so the best evidence-backed improvement is to eliminate the next repeated cost rather than tune a cache that is already hitting.
- If the standalone dashboard workflow must remain for other callers, extract shared scripts instead of duplicating logic.
### Control Plane
- Correlation ID: `33937355490-193`
- Central repository: `githubnext/gh-aw-cao`
- Control plane run: `https://github.com/githubnext/gh-aw-cao/actions/runs/33937355490`
### References
- `docs.yml` runs: `33937171835`, `33935304449`, `33934891156`, `33934530661`, `33933937325`, `33933221059`, `33931735389`, `33931071494`, `33930867167`, `33930696456`, `33929783050`, `33929584444`
- Failed runs disclosed: `33935427770`, `33936332934`
- Matched `dashboard-build.yml` runs: `33937177040`, `33935310471`, `33934897261`, `33934538584`, `33933943156`, `33933227625`, `33931752018`, `33931079683`, `33930874096`, `33930717272`, `33929791156`, `33929591566`
> Generated by [SelfCare / Docs Build Time](https://github.com/githubnext/gh-aw-cao/actions/runs/33937559831) · pi · gpt54 · 60.3 AIC · ⌖ 8.59 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 19, 2026, 2:01 AM UTC
Contributor guide
Research direction
Start by comparing the dashboard job and build job in .github/workflows/docs.yml with the existing build job in .github/workflows/dashboard-build.yml. Run a baseline docs.yml build, then verify the local assembly preserves cache mode, required activity snapshots, and the /cao Pages output. Done means the dashboard dispatch and artifact download are removed from the critical path and five post-change runs meet the stated timing and content checks.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github-actions
- Domain
- build-system, ci-cd, devops
- Issue type
- Refactor
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 68/100