githubnext / githubnext/gh-aw-cao

[self-care:docs-build-time-investigator] Skip cache-mode dashboard redispatch when a fresh reusable dashboard bundle already exists

Closed
#8,281 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
For recent scheduled docs deploys, the workflow spends most of its time waiting on a dispatched dashboard build even when the dashboard workflow reuses cached activity data and produces a small artifact. A cache-first fast path in `.github/workflows/docs.yml` for cache-mode schedule runs is likely to cut about 47 seconds from the median 88.5-second execution time without reducing freshness guarantees for live runs.

### Timing evidence
Evidence window: 2026-09-10T05:32:21Z to 2026-09-10T08:31:14Z.

Comparable sample: 6 successful scheduled `docs.yml` runs and their 6 dispatched `dashboard-build.yml` child runs.

Parent `docs.yml` timings:
- workflow queue median/p90: 0s / 0s
- workflow execution median/p90: 88.5s / 106.5s
- `dashboard` job median/p90: 38s / 41s
- `build` job median/p90: 31s / 36.5s
- `deploy` job median/p90: 9s / 10s
- `dashboard` step `Dispatch dashboard build` median/p90: 33s / 36s

Child `dashboard-build.yml` timings:
- `activity` job median/p90: 5s / 6s
- `build` job median/p90: 14s / 20s
- `Build Dashboard Language sources` step median/p90: 1.5s / 2s
- `Upload dashboard artifact` step median/p90: 2.5s / 3s

Trusted cache evidence:
- Parent `build` job skipped `Install dependencies` and `Save node_modules` in all 6 samples, confirming node_modules cache hits.
- Child `activity` job skipped `Dispatch activity refresh` in all 6 samples, confirming cached activity snapshot reuse in cache mode.
- Parent `Restore dashboard from cache` remained near-zero, but the workflow still waited for a fresh child run before mounting the dashboard artifact.

Confidence: medium-high. The sample is recent, all-successful, and like-for-like for scheduled cache-mode deployments, but it covers only one morning window after recent workflow changes.

### Bottleneck
The repeated cost is not Astro docs generation or Pages deploy. It is the unconditional dashboard-build dispatch path in cache mode:
- `.github/workflows/docs.yml` always runs the `dashboard` job and waits for `Dispatch dashboard build` before the parent `build` job can continue.
- `.github/workflows/dashboard-build.yml` already has a cache-mode fast path that checks for cached activity data and skips live activity refresh when available.

In these samples that fast path hit every time, yet the parent workflow still paid roughly 33 seconds of dispatch/startup/wait time plus a 14-second median child build to recreate a dashboard bundle whose expensive input was already cached.

### Recommended changes
In `.github/workflows/docs.yml`, add a cache-first gate for scheduled or cache-mode runs before dispatching `dashboard-build.yml`:
1. attempt to restore or download the latest reusable dashboard bundle produced by a recent successful cache-mode `dashboard-build.yml` run;
2. only dispatch `dashboard-build.yml` when no acceptable cached dashboard bundle is available, when the bundle is stale relative to the desired freshness window, or when `mode=live`;
3. keep the current child workflow path as the fallback and for all live refreshes.

Relevant source locations:
- `.github/workflows/docs.yml`: `dashboard` job and `build` job steps `Dispatch dashboard build`, `Restore dashboard from cache`, `Mount dashboard at /cao`
- `.github/workflows/dashboard-build.yml`: `activity` job `Check for a cached activity snapshot`, `Dispatch activity refresh`, and the `build` job cache/artifact save steps

### Expected effect and validation
Expected effect:
- save about 33 seconds median directly in the parent `Dispatch dashboard build` step;
- avoid most of the 14-second median child build on cache-hit runs;
- reduce scheduled cache-mode median workflow time by about 47 seconds total, from 88.5s to roughly low-40s, a reduction of about 53% if the dashboard bundle fast path hits consistently.

Validation plan:
1. compare at least 5 successful scheduled cache-mode runs before and after the change;
2. confirm the new fast path serves the cached dashboard bundle on most schedule runs;
3. verify no regression in dashboard content freshness by checking that live runs still dispatch and rebuild when required;
4. track median/p90 for `docs.yml` workflow execution plus `dashboard`, `build`, and `deploy` jobs.

### Caveats
- This recommendation is only safe if the reused dashboard bundle has a clear freshness policy tied to the same cache-mode semantics already used for activity data.
- Do not bypass the child workflow for `mode=live` or when the cache cannot prove freshness.
- If the implementation relies on cross-run artifact lookup instead of a stable cache key, ensure the lookup logic is deterministic and fails closed.
- Some recent push-triggered runs and several earlier failed schedule runs were excluded from the comparable sample by design.

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

### References
- Workflow source: `.github/workflows/docs.yml`
- Workflow source: `.github/workflows/dashboard-build.yml`
- Parent runs:
- https://github.com/githubnext/gh-aw-cao/actions/runs/34441469666
- https://github.com/githubnext/gh-aw-cao/actions/runs/34446042920
- https://github.com/githubnext/gh-aw-cao/actions/runs/34450809914
- https://github.com/githubnext/gh-aw-cao/actions/runs/34451648131
- https://github.com/githubnext/gh-aw-cao/actions/runs/34452995123
- https://github.com/githubnext/gh-aw-cao/actions/runs/34455609861
- Child runs:
- https://github.com/githubnext/gh-aw-cao/actions/runs/34441479210
- https://github.com/githubnext/gh-aw-cao/actions/runs/34446054092
- https://github.com/githubnext/gh-aw-cao/actions/runs/34450818896
- https://github.com/githubnext/gh-aw-cao/actions/runs/34451659739
- https://github.com/githubnext/gh-aw-cao/actions/runs/34453006823
- https://github.com/githubnext/gh-aw-cao/actions/runs/34455663739

> Generated by [SelfCare / Docs Build Time](https://github.com/githubnext/gh-aw-cao/actions/runs/34455759857) · pi · gpt54 · 34.2 AIC · ⌖ 7.13 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 24, 2026, 8:42 AM UTC

Contributor guide

Open the contributing guide

Research direction

Start with the dashboard job and the Dispatch dashboard build, Restore dashboard from cache, and Mount dashboard at /cao steps in .github/workflows/docs.yml. Compare them with the cache and artifact handling in .github/workflows/dashboard-build.yml, then validate at least five scheduled cache-mode runs while confirming live runs still rebuild and freshness rules are respected.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions
Domain
ci-cd, devops, performance
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
58/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.