Port releases break docs CI; publish by dispatch without a manifest

[tony]

Summary

Every commit and pull request in this repository fails test whenever any of the ten ports publishes a release, until someone commits a refreshed site/src/data/registry.json. The per-commit gate compares that committed file against live package registries, so its result depends on other repositories rather than on the commit under test. Separately, the shell deploy has been merging none of the ports' published version manifests.

Motivation

• scripts/test-all.sh runs node scripts/gen-registry.mjs --check online inside the test job, and test.yml passes GITHUB_TOKEN so it reliably reaches the APIs. gen-registry.mjs documents --offline as the mode "For CI jobs that must not depend on eight third-party services"; the gate does not use it.
• Releases land in two phases, tag first and package later. For libtmux-dotnet v0.0.0-alpha.17 the release ran 15:11 to 15:31 UTC and NuGet published at 15:25 UTC, so a refresh committed in between went stale within minutes and Refresh the Rust registry entry and API model for alpha.14 #25 failed this step twice in an hour for ports it did not touch.
• Most commits to registry.json exist only to refresh it, and refreshes ride along inside unrelated pull requests (for example Run the TypeScript workspace CLI with plain yarn dlx #23 and Refresh the Rust registry entry and API model for alpha.14 #25). Nothing else detects a release: no workflow runs on a schedule, and the shell deploy ships the committed file as is.

Also found

The shell deploy downloads manifest/<port>.json with 2>/dev/null || true, but the shell's IAM role has no read access to manifest/*. The last three successful deploys each logged merge-version-manifests: merged 0 published port fragment(s) (for example run 36317927860), while the manifests exist and are public, so ports' version lists and defaults never reach versions.json or the default-version store.

Proposal

Invariants, the non-negotiable part: a pull request's CI result depends only on the commit and its pinned inputs; a release reaches the site without a human commit; a port can publish only its own prefix, through a reviewed workflow. Everything below is non-binding intent, from smallest to largest.

Fix the manifest merge

Grant the shell role s3:GetObject (and, for the options below, put and delete) on manifest/* in the infrastructure Terraform, and let the copy fail loudly when a manifest exists but cannot be read.

Offline gate plus a scheduled refresh

The gate runs gen-registry.mjs --check --offline. An hourly workflow regenerates the registry online and opens or updates one refresh pull request, auto-merged when green, as Homebrew autobump and nodejs.org auto-merge do. The bot must open its pull request with a GitHub App installation token, because events created by GITHUB_TOKEN do not start workflow runs (docs). The probe records a tag only once the registry carries that version.

Registry computed at deploy time

The shell deploy regenerates the registry against the live APIs, falls back to the last published copy in the bucket, publishes the resolved file, and gains schedule and workflow_dispatch triggers. registry.json leaves git; the gate checks rendering against a fixture.

Dispatch-driven, manifest-free publishing

A workflow_dispatch here with inputs such as ports (all or a list), ref (tag, branch, SHA or latest), version, version-kind and is-default (up to 25 inputs). It fans out to each port's own docs workflow with a GitHub App installation token minted by actions/create-github-app-token, since GITHUB_TOKEN cannot reach another repository. Each port builds its tree and API model with its native toolchain and records its released version in its bucket manifest, and the shell composes install commands, version lists and API pages from the bucket, so no committed manifest remains. libtmux-ruby and libtmux-lua already accept these inputs (example).

Port roles can trust only this repository's reusable workflow rather than each caller: AWS IAM supports token.actions.githubusercontent.com:job_workflow_ref as a condition key (AWS docs, GitHub docs). A reusable workflow's uses: ref cannot be an expression (docs), so port pins are bumped by Renovate or Dependabot. The Terraform GitHub provider can own the environments, organization variables, the App's repository list and rulesets alongside the IAM changes.

Not doing

Changing docs.rs as the canonical Rust API reference, or the separate Python documentation site.

References

• libtmux/libtmux-rs#35 removed a leftover docs-site publish trigger; libtmux-ts docs.yml still carries the same one.
• reusable-deploy.yml: the deploy contract; it requires a distribution secret it never uses and says rs, go and java never publish through it, which they do.
• lychee-action and CPython's docs job: live external checks run on a schedule, not in the pull-request gate.

[tony]

Another verified finding for the design: /en/<port>/latest/ has two writers for the seven ports that do not set publishesOwnTree (rs, ts, go, java, dotnet, cxx, swift). The shell deploy's publish-root syncs en/rs/latest/ (for example run 36332666712), and libtmux-rs's own docs.yml publishes PREFIX: en/rs/latest through the reusable deploy (run 36330416962). Both use sync --delete, so whichever deploy ran last owns the tree, and the two builds read different inputs: the port's reads its own checkout, the shell's the committed data here.

This points the dispatch-driven design at fan-out with one owner per prefix: every port publishes its whole tree, as Ruby and Lua already do, the shell stops assembling port latest trees, and the shell's IAM grant narrows to the paths it actually owns.

[tony]

Progress on this issue. Each item links the run that proves it.

Landed

CI no longer depends on another repository publishing

• Check the committed registry offline; record a tag only once published #28: the gate runs gen-registry.mjs --check --offline, and the registry records a tag only once its package is published.

Manifests merge, loudly

• Merge every published port manifest into versions.json, loudly #29, with infrastructure changes: the shell role can read manifest/*, and the error suppression is gone.
• The first deploy afterwards logged merged 10 published port fragment(s), where every earlier deploy merged 0 (run 36340071169).

A release reaches the site without a commit

• Resolve the package registry at deploy time #30: deploy-shell.yml resolves the registry against the package registries at deploy time, publishes registry.json (max-age=60), and runs hourly and on dispatch.
• First publish: run 36342768348.
• A dispatch deployed successfully: run 36351100152.
• The hourly schedule works: its first run found the registry unchanged and skipped the build and publish (run 36354994809). GitHub fired it about an hour late under load.

Deploys upload only what changed

• Upload only the files a shell deploy changed #35: publish-root (en) used to upload about 43,000 unchanged objects in about 15 minutes.
• Steady state after the change: 3 of 60,761 files uploaded, and the step takes 5 min 25 s (run 36351100152).

Every port publishes versioned docs from its own source

• Build any port's versioned docs from its source #36 adds port-docs.yml. It resolves versions from the event, builds from the port's source, and checks out this repository at job.workflow_sha, so a port pins libtmux/docs once.
• Emit Swift's symbol graph before its build #39 adds Swift's symbol graph, and Let libtmux-swift own its version tree #40 makes Swift own its tree. Let ported docs own their version trees #32 moves tree ownership to the other six ports, so the shell stops overwriting their trees.
• Callers, each about 100 lines instead of about 240:
  • Docs(ci[deploy]): Publish each release's docs libtmux-rs#37
  • Docs(ci[deploy]): Publish each release's docs from source libtmux-ts#39
  • Docs(ci[deploy]): Publish each release's docs from source libtmux-go#28
  • Docs(ci[deploy]): Publish each release's docs from source libtmux-java#39
  • Docs(ci[deploy]): Publish each release's docs from source libtmux-dotnet#39
  • Docs(ci[deploy]): Publish each release's docs from source libtmux-cxx#23
  • Docs(ci[deploy]): Publish each release's docs from source libtmux-swift#19
• Each port's first master publish succeeded: ts, java, go, dotnet, cxx and swift in runs 36353672621, 36353676918, 36353681060, 36353685690, 36353689592 and 36353694653; rs in run 36354465464.
• libtmux-rs's dispatch of v0.1.0-alpha.14 found a bug: the immutable-tag guard in reusable-deploy.yml failed every release-version publish. That is why no port had ever published one (run 36355232670).
  • Let a release version publish at all #42 fixes it, and all seven ports now pin it.
  • On the fixed pin, one dispatch published /en/rs/v0.1.0-alpha.14/ with max-age=31536000, immutable (run 36358012559). It is the first release version on the site.
  • Dispatching the same tag again rebuilt byte-identical output, and the guard skipped the upload (run 36358890249).
  • The next alias from the same dispatch published (run 36355234730).

One dispatch publishes any set of ports at a ref

• Publish any set of ports at a ref from one dispatch #45 adds publish.yml. It plans, dispatches each port's docs.yml with the LIBTMUX_DOCS_DISPATCH_TOKEN fine-grained token, waits for each run, then redeploys the shell.
• Dry run: planned 18 versions and dispatched nothing (run 36363886176).
• ports=all ref=release: one dispatch published the newest release and next for ts, rs, go, cxx, swift and ruby, and all 12 pages serve 200 (run 36363936862).
• java and dotnet failed at startup while their pin (libtmux/docs 6f721f90, from an unmerged branch) did not resolve. Re-running ports=java,dotnet ref=release published both, and all four pages serve 200 (run 36365360455). Eight of nine ports now have their newest release on the site.
• lua's v0.1.0alpha1 is refused by lua's own exporter, and that is its gate working. The release annotates only libtmux.Server as a class, and the exporter requires Pane, Session, Window and the rest. The next lua release publishes normally.

A release publishes itself

• libtmux-rs 0.1.0-alpha.15: pushing the libtmux@v0.1.0-alpha.15 tag ran docs.yml with no dispatch (run 36370968293).
  • It published /en/rs/v0.1.0-alpha.15/ with max-age=31536000, immutable, and moved next to v0.1.0-alpha.15.
• Pushing the release's four tags in one git push created no events. GitHub makes no push events when more than three tags are pushed at once. Pushed one at a time, each tag started its own run.
• The site's install commands:
  • crates.io served alpha.15 before registry.json changed. The hourly schedule had dropped three slots in a row under load.
  • Check the registry four times an hour #48 runs the check four times an hour.
  • registry.json moved to alpha.15 at 04:08 through the deploy of Check the registry four times an hour #48's own merge commit, so the no-commit path through the schedule still awaits a live run.

Least privilege

• Every port role trusts only reusable-deploy.yml, by its job_workflow_ref claim at a SHA or tag, never a branch.
• The docs environments admit master plus each port's release-tag pattern.
• The IAM simulator allows the rs role on en/rs/* and manifest/rs.json, and denies en/ts/*, manifest/ts.json and registry.json.
• The shell role is now explicitly denied writes below <locale>/<slug>/ for the nine ports that own their trees; their landing pages stay writable.
  • Simulator: en/rs/latest/… and ja/lua/latest/… are explicitDeny, while en/rs/index.html and en/py/latest/… are allowed.
  • A shell deploy under the new policy succeeded, uploading 3 of 24,952 files, and publish-root (en) took 2 min 49 s (run 36359864697).
• tmux-python/libtmux's docs environment admitted any branch. It now admits master (libtmux.git-pull.com) and docs-site-deploy (the py tree here).

Defaults and docs

• Docs(ci): Keep a stable release the default through trunk pushes libtmux-ruby#6 and Docs(ci): Keep a stable release the default through trunk pushes libtmux-lua#8: trunk stays the default only until a stable release, as port-docs.yml does.
• Describe how a port publishes through port-docs.yml #44: docs/ci.md documents the port-docs.yml caller and the dispatch command.

Checks that checked less than they appeared to

• Check the API model's content, not its revision #33: the API model check compares content, not the revision stamp.
• Stop stamping the mention index with the build time #37: the mention index no longer gets a timestamp on every build.
• Say every port publishes, and stop requiring the unused secret #34: corrects the claim that rs, go and java never publish.

Infrastructure hygiene

• Port previews under <locale>/<port>/pr-* now expire after 30 days (20 lifecycle rules).
• A one-time invalidation cleared manifest/* copies cached before the short-TTL behavior existed. One had been served for five hours.

Open

• Pin updates by Dependabot
  • Ports now pin libtmux/docs once, but this repository has one tag (v0.1.0-alpha.1) and no releases, so Dependabot has nothing to bump to.
  • Needs a tagging policy for the reusable workflows.
• py publishes from an unmerged branch. tmux-python/libtmux's docs-site-deploy branch is marked "DO NOT MERGE". Moving that workflow to master is the owner's call.
• Two flaky tests surfaced along the way. Both lost their tmux server mid-test: libtmux-rs tmux-mcp run_frame_preserves_inherited_error_and_debug_traps, and libtmux-swift "a retained run releases only after authenticated disappearance" on tmux 3.2a.
• Committed registry and API models stay, deliberately.
  • registry.json is the pinned input that keeps pull-request CI independent of other repositories (invariant 1). It is also the deploy's last-resort fallback. Production values come from the deploy-time resolution.
  • The API models now feed only the shell's Pagefind index, sitemap and cross-links for port-owned trees.
  • Removing them needs per-port Pagefind bundles merged at search time (Pagefind's mergeIndex). That is a follow-up.