Skip to content

docs: /releases is always one release behind — the deploy races the GitHub Release #3035

Description

@mfal

/releases cannot show the release it was built for. The docs deploy and the
GitHub Release it renders are triggered by the same push, and the release is
created last — so every promotion ships a docs site that is one release behind,
until the next push to main happens to rebuild it.

Measured on the 1.1.0 promotion

Build & Deploy main to mittwald 12:09:13 → 12:15:28
GitHub Release 1.1.0 created 12:13:07

The next build ran while the release did not exist yet. The deployed page
listed up to 1.0.16; 1.1.0 was absent. Verified against the served page, not
inferred. A manual re-run of the deploy fixed it.

Why it is structural

  • getReleases() in apps/docs/src/lib/releases/githubReleases.ts fetches
    api.github.com/repos/mittwald/flow/releases at build time — the page is
    a static export, so whatever the build saw is frozen into the HTML.
  • deploy-main.yml triggers on push to main.
  • publish.yml triggers on the same push but creates the GitHub Release in its
    last step, after npm publish. That deferral is deliberate and should stay:
    pushing the release before a successful publish is what let a failed publish
    ratchet a line ahead of npm.

So the deploy is racing a release that is designed to arrive later. Nothing in
the current wiring can win that race.

The same gap applies to any edit of a past release body: correcting the
1.0.0 notes updated GitHub immediately, while /releases kept serving the old
text until the next deploy.

Options

  1. Trigger the deploy on the release event. Add release: [published] to
    deploy-main.yml. Simplest, and it also covers edits if [edited] is
    included. Costs one extra full docs build per release.
  2. Dispatch the deploy from publish.yml after the release step. Keeps the
    trigger explicit and ordered, but couples the two workflows.
  3. Fetch client-side (or via ISR) instead of at build time. Removes the race
    entirely and makes edits appear without a deploy, but gives up the static
    export for this page and puts a GitHub API call in the visitor's path — it
    would need caching and an unauthenticated-rate-limit story.

Option 1 is the smallest change that closes the race. Option 3 is the only one
that also makes release-body edits show up on their own.

Whichever is chosen, concurrency: deploy-main-${{ github.ref }} with
cancel-in-progress: false already serialises deploys, so an extra trigger
queues rather than clashing.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationgithub_actionsPull requests that update GitHub Actions code

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions