[coretl]

blueapi adopted this pipeline on 2026-08-05 and switched the PR previews off on 2026-08-06 because publish was adding many minutes to every PR. That was the right call on the evidence, and this is the fix.

Independent of the workflow_run experiment — correct under either trigger.

The measurement

step, blueapi PR run 31081562099	time
Gather release artifacts — 188 releases listed, 131 docs.zip downloaded one at a time	114 s
Gather branch CI artifacts — 26 open PRs, one full artifacts-API pagination each	175 s
Upload Pages artifact — 452,549,958 bytes	36 s
Deploy to GitHub Pages	280 s
deploy job total	654 s

The docs build is 27–45 s; everything else in their CI finishes by ~200 s. Publish alone took the run from ~200 s to ~750 s.

The cause is that the deploy's cost is O(whole site), not O(what changed): every event re-downloaded ~453 MB of immutable release assets and re-uploaded a 452 MB artifact, doing identical work regardless of which PR fired it.

And 452 MB is 45% of Pages' hard 1 GB artifact limit, growing ~5 MB per release. That is ~110 more releases until deploys simply start failing, with nothing on the way to say so.

What changed

Release gather — assemble.mjs picks the set first, an actions/cache entry keyed on exactly that set of asset ids supplies the zips already seen, and only misses are fetched, in parallel. Assets are immutable, so steady state is a full hit and a new release downloads one zip. Cached files are named by asset id, not tag, so a re-cut release can never be served stale; the cache is pruned to the published set. Saved only from the default branch — a cache written on a PR ref is scoped to that PR and would just churn the 10 GB quota.

Artifact gather — paginate once and index newest-artifact-per-head-SHA, instead of re-paginating per open PR. Downloads in parallel.

max-releases — publish only the N most recent releases. Defaults to 0 (unlimited), so upgrading never silently deletes versions from an existing site; the tutorial's shim ships 20. It goes in the shim's with: as a literal, not threaded from ci.yml, so it applies on every path rather than only the inline one. Past 700 MB a deploy warns.

Ranking is on created_at, never on parsing version numbers. published_at lies: blueapi's 1.3.2-a9 was created 2025-10 and re-published 2026-07, and under published_at it outranked the genuinely newer 1.11.3. Verified against their real 188-release payload — max-releases: 20 takes the released half from 453 MB to 73 MB.

_sources/ → actions/cache — the default branch's durable docs.zip was published into the site, shipping a multi-megabyte zip inside every Pages artifact forever. It moves to the Actions cache, content-addressed so an unchanged branch adds no entry.

The trade is real and worse, deliberately: cache entries are evicted after 7 days unread and by LRU past 10 GB, so a repo quiet for over a week whose main CI artifact has also expired loses the rung and hard-fails — loudly, and fixed by one push. _sources/ is no longer written; its read survives as a deprecated one-shot rung so a site last deployed by an older publish.yml still has a source on its first upgraded deploy.

The bit that needed care

scripts/migrate.sh gated the irreversible gh-pages delete on _sources/<default>.zip returning 200 from the live site. That file no longer exists, so the guard is replaced — with a stronger one. It now requires both that /<default>/ is live in the new site and that a non-expired docs artifact exists for the default branch, i.e. its CI really builds docs.zip now.

The old check passed while /<default>/ was still coming from the migration seed — exactly the state where gh-pages remains the only real copy. It was only safe because _sources was permanent; with an evictable cache-backed copy it would not have been.

Testing

publish.yml's gather steps were previously verifiable only by merging and watching a real deploy. test/workflow-harness/ loads them straight out of the YAML — so the tests cannot drift from the workflow — and runs them against a mock gh. 27 checks covering the cap, cache hit/miss/prune, the artifact index, fork approval, the full default-branch fallback chain, the zip-shape contract, the size guard, an empty repo, and each of the four failure modes.

It caught two real bugs while being written. npm run test:workflows, wired into _test.yml.

Also 11 new selectReleases unit tests (34 total, all passing), and the strict docs build is clean.

Expected result

gather ~25 s, extract ~5 s, upload ~12 s, deploy ~30–60 s ⇒ ~100 s. Starting after docs (~50 s) that finishes around 150 s, inside blueapi's 195 s system-test — off the critical path in wall-clock terms without changing the trigger at all.

Once tagged, blueapi should bump the pin, set max-releases, and revert #1614: their tags-only gate is why the site never self-heals. Handover text is written up separately.

🤖 Generated with Claude Code