fix(release): dispatch the docs deploy instead of relying on release: published

[devops-thiago]

What type of PR is this?

• 🐛 Bug fix
• 🏗️ CI/CD
• 📝 Documentation

Description

The docs site has never deployed itself, including for v0.6.2 just now.

docs.yml declares release: published, but the release job creates the release with the default
GITHUB_TOKEN, and GitHub does not start workflow runs for events that token raises — the same
recursion guard already documented for the bump PR. The trigger has fired zero times in the
repo's history:

docs.yml runs by event: pull_request 96, workflow_dispatch 4, release 0

Every release through v0.6.2 published its docs by hand.

On the v* tag policy from #715. That was a real and separate bug — the build runs against the
tag ref, so the deploy would have been refused by the github-pages environment even if the event
had fired. But it was not why nothing ran, and my note in that PR saying the next release would
deploy itself was wrong. What it did fix is the manual path: dispatching against a tag works now for
the first time, which is how v0.6.2's docs went live.

The fix. A publish-docs job in release.yml dispatches docs.yml against the release tag once
the release exists. workflow_dispatch is exempt from the recursion guard. Three details:

• Gated on update_latest, like bump-version. The live site tracks the highest release, so a
  patch cut on an older line must not republish the site from its tag.
• Fails loudly rather than warning. A silent miss is what left the site four versions behind.
• Runs after release, so the docs never go live for a version whose release did not complete.

The declared release: published trigger stays on docs.yml, because a release published by hand in
the UI does fire it. Its comment now says so instead of implying it is the live path.

docs/RELEASING.md described only the tag policy and claimed the next release would deploy itself.
It now separates the two conditions, records that the trigger does not fire on its own, and gives the
command to republish a tag after a docs hotfix.

Related Issues

Follows #715, which added the github-pages tag policy and the docs-freeze procedure.

How Has This Been Tested?

• Manual testing

• actionlint .github/workflows/release.yml .github/workflows/docs.yml → clean

• npm run build in website/ → all internal links valid

• The dispatch path itself was exercised by hand against v0.6.2
  (gh workflow run docs.yml --ref v0.6.2): build and deploy both succeeded, and the live site now
  serves v0.6.2 with v0.6.0 and v0.6.1 in the picker

• End to end, the publish-docs job can only be proven by the next release

No production code changes.

Checklist

• My code follows the project's coding standards
• I have performed a self-review of my own code

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[thrillhousebot]

🤖 ThrillhouseBot PR Summary

What this PR does

Adds a `publish-docs` job to release.yml that dispatches the Docs workflow against the release tag after `verify`/`release`/`promote` complete, gated on `update_latest`, because `release: published` never fires for pipeline-created releases (the GITHUB_TOKEN recursion guard). It also rewrites docs/RELEASING.md and adds comments in docs.yml documenting that the trigger only fires for hand-published releases.

⚠️ Description vs. Implementation

Every mismatch found between the description and the change is reported as a finding below, so it is not repeated here.

Control-Flow Diagram

🔀 Show diagram

flowchart TD
  A["Release job creates release via GITHUB_TOKEN"] --> B["Promote job sets update_latest"]
  B -->|"true"| C["publish-docs job runs"]
  B -->|"false"| D["No dispatch: patch on older line"]
  C --> E["gh workflow run docs.yml --ref TAG"]
  E --> F["docs.yml builds site from tag ref"]
  F --> G{"github-pages env admits tag?"}
  G -->|"yes"| H["Deploy succeeds; live site tracks new release"]
  G -->|"no"| I["Deploy fails; release pipeline already green"]

Loading

Changes Overview

• Files changed: 3
• Lines added: +68
• Lines removed: -8

Changed Files

File	Change	Summary
.github/workflows/docs.yml	Modified	Comment-only change clarifying that the release:published trigger fires only for hand-published releases.
.github/workflows/release.yml	Modified	Adds publish-docs job that dispatches docs.yml against the release tag, gated on update_latest.
docs/RELEASING.md	Modified	Rewrites the publishing-the-docs section: dispatch vs trigger, tag policy requirement, manual republish command.

Risk Assessment

Risk	Count
🔴 Critical	0
🟠 High	0
🟡 Medium	1
🔵 Low	0

Things to double-check

1 lower-confidence finding

• MEDIUM: Comment claims step fails loudly on deploy failure, but dispatch does not monitor the run (.github/workflows/release.yml:354) (low confidence — verify before acting)

⚠️ Required CI Checks Status

Some required checks are still pending or have failed:

Check	Type	Status	Detail
dependency-review	check-run	⏳ Pending	-
frontend	check-run	⏳ Pending	-
test	check-run	⏳ Pending	-
format	check-run	⏳ Pending	-
trivy	check-run	⏳ Pending	-

---

Automated review by ThrillhouseBot. Reply with /review to re-run.

[thrillhousebot]

ThrillhouseBot noted 1 lower-confidence item(s) under Things to double-check in the PR summary (not posted as inline threads):

• MEDIUM: Comment claims step fails loudly on deploy failure, but dispatch does not monitor the run (.github/workflows/release.yml:354)
  The comment at lines 352-353 asserts that this step surfaces the github-pages protection-rule failure: # protection rules". Failing here is deliberate — a silent miss is / # what let the site sit four versions behind. But the code at line 354, gh workflow run docs.yml --repo "$GITHUB_REPOSITORY" --ref "$TAG", only creates the workflow run: GitHub CLI's documented behavior is that gh workflow run exits as soon as the dispatch is accepted and does not wait for or report the run's outcome (verify with gh workflow run --help). The "not allowed to deploy to github-pages" failure the comment describes happens inside the dispatched docs.yml deploy job, after this step has already exited 0, so the whole release pipeline stays green while the live site silently stays stale — the exact silent miss the change claims to eliminate. The step does fail loudly for dispatch-time errors (bad ref, missing workflow_dispatch), so the primary fix is effective; the gap is specifically deploy-stage failures. Either watch the dispatched run (resolve its run id, e.g. gh run list --workflow docs.yml --branch "$TAG", then gh run watch --exit-status) or correct the comment and RELEASING.md to state that deploy-stage failures surface only in the Docs workflow's Actions tab, not in release.yml.

[thrillhousebot]

🤖 ThrillhouseBot — changes since the last review

• New findings this round: 0
• Previous findings resolved: 1
• Previous findings still open: 0

[thrillhousebot]

ThrillhouseBot found no issues in this PR, but some checks are still pending or failed:

• Check test is pending
• Check trivy is pending
• Check frontend is pending
• Check format is pending
• Check dependency-review is pending

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud