[coretl]

Implements the migration the live experiment proved viable. Net −119 lines while adding a test file, because this is almost entirely subtraction.

What the experiment settled

Pages stamps every deployment with pages_build_version = GITHUB_SHA and silently no-ops a repeat (deploy-pages#383) — but only for some events. Four consecutive deploys at the identical build version b24237484c3b445469c2db4ef161410a185fcdbc — a push to main, a tag cut on that same commit, and two pushes to one PR — and every one updated the live origin. workflow_run forces a re-serve exactly as workflow_dispatch does.

That was not predictable from the docs, which is why it was tested rather than reasoned about.

What that deleted

gone	why it existed
re-dispatch job	a tag's same-SHA deploy was dropped; it bounced through workflow_dispatch. Now it re-serves directly
publish-dispatch.yml	a reusable workflow can't be workflow_dispatch'd cross-repo, so the trampoline needed a local file to re-fire
version-name injection + threading	a nested publish ran inside the build's own run, so the gather couldn't discover it. workflow_run fires after completion — verified in the baseline, where both injection steps skipped and the site still assembled
warn job	a fork's CI never reaches the engine now
retry-until, wedged-origin retry	tied to the trampoline; the engine no longer needs actions: write

Also gone: the tag/docs.zip asset race that made blueapi permanently one release behind. release.yml runs inside the CI run that publish waits on, so the asset is always attached first. That's why #62 was closed rather than merged.

Shape

ci.yml builds and stops. publish.yml — the file consumers carry, and the one place <tag> is pinned — triggers on workflow_run (CI completing) plus workflow_dispatch (fork previews, manual re-deploys), and calls publish-gh-pages.yml.

The engine is renamed from publish.yml so this repo can dogfood the consumer filename exactly rather than approximating it.

The trap this introduces

Under workflow_run, GITHUB_SHA and github.ref are always the default branch's HEAD, never the built commit — a PR-triggered deploy reports refs/heads/main.

Both cache-save steps gated on github.ref. That would have been true for every PR-triggered deploy, each writing a cache scoped to a PR nothing else can read. They now test github.event.workflow_run.head_branch.

That lives in an if: expression, which the gather harness can't reach — hence test_shape.py, 21 structural assertions covering the cache conditions, the caller's two guards, and the absence of the deleted machinery. All of those fail open, so nothing would announce a regression.

Security

workflow_run runs with a write token even when a fork's PR triggered it — the pwn-request shape. The caller requires head_repository.full_name == github.repository, so a fork's build never reaches the engine automatically. Maintainers preview one by dispatching with pr, which pins approval to that head SHA.

Also here

cancel-in-progress: true — safe now that publish has its own run (it previously marked unrelated PRs' CI cancelled), and correct because every deploy reconstructs everything.

One unrelated fix: .devcontainer/devcontainer.json and package-lock.json were swept into #64 by a git add -A. The lockfile change stripped libc fields from Biome's platform-specific optional deps, which is how npm picks glibc vs musl. Both restored to their pre-#64 state.

Verification

npm test (34), npm run test:workflows (gather + shape), npm run docs --strict all pass. The real proof is the merge deploy and the v0.25.0 tag that follows.

BREAKING: consumers add publish.yml, delete publish-dispatch.yml, remove the publish job from ci.yml, and re-pin to publish-gh-pages.yml. Migration guide written up for blueapi.

🤖 Generated with Claude Code