ci: deploy docs site on release publish instead of every unstable push

[shane-moore]

Problem, Evidence, and Context (Required)

• The docs workflow deploys anchor.sigmaprime.io on every push to unstable, so docs for unreleased CLI flags go live weeks before a binary exists, and during each release window the site advertises versioned download URLs that 404 (the version bump merges to unstable before the release is published).
• Operators are currently seeing docs for flags their binary rejects.
• Separately, the Linux install example uses an arch-less tarball name that no release asset matches, and the version-sync regex mangles arch-qualified names at build time.
• Closes ci(docs): deploy docs site on release publish instead of every unstable push #1209 (alternatives considered and rollout details are recorded there).

Change Overview (Required)

• docs.yml now triggers on release: published (prerelease-guarded) plus a bare workflow_dispatch for manual redeploys; deploys serialize under a constant concurrency group with cancel-in-progress: false so an in-flight s3 sync --delete is never killed halfway.
• sync-version.js filename regexes drop the greedy optional suffix group that swallowed the architecture component; the installation example is now arch-qualified; the docs README documents the new publication timing.
• Reading order: docs.yml (the behavior change), then sync-version.js + installation.mdx (content fix), then README.md.
• Intentionally unchanged: the build itself, linkcheck and CLI-reference checks on PRs/unstable, and the S3 sync mechanics.

Risks, Trade-offs, and Mitigations (Required)

• The new trigger and the manual-dispatch button only take effect once this file reaches stable (default branch) at the next release; until then the live site freezes at its current content (status quo, self-corrects at next release publish).
• Merging this stops unstable-push deploys immediately (push events read the workflow file at the pushed commit; no final unstable deploy fires).
• Docs-only fixes between releases no longer publish automatically; path is cherry-pick to stable and gh workflow run docs.yml --ref stable.
• Publishing a stale draft release would redeploy that tag's docs; accepted as low-likelihood and recoverable via a manual redeploy from stable.

Validation (Required)

• actionlint clean on the modified workflow; node --check clean on sync-version.js.
• Regex fix verified with a standalone node repro: arch-qualified names now survive version rewriting (previously anchor-v1.1.0-x86_64-... became anchor-vX.Y.Z-...).
• End-to-end trigger behavior is only observable at the next release publish; first post-release deploy should be checked against the live site.

Rollback (Required for behavior or runtime changes; optional otherwise)

• Revert the commit; the previous push-to-unstable deploy behavior returns on the next unstable push. No data or config impact; the S3 bucket is fully rewritten by any subsequent deploy.

[shane-moore]

@claude, please take a look

[claude-code-actions-sigp]

Claude finished @shane-moore's task in 1m 28s —— View job

---

PR Review: Deploy docs on release publish

• Read changed files (docs.yml, sync-version.js, installation.mdx, README.md)
• Analyze workflow trigger + concurrency changes
• Analyze regex fix in sync-version.js
• Verify installation example correctness
• Post review

---

Reviewed against origin/unstable. This is a tidy, well-motivated change and the PR description does an excellent job laying out the reasoning and rollout caveats. No blocking issues found.

Workflow (docs.yml) — correct

• Trigger swap (push: unstable → release: published + workflow_dispatch) directly addresses the "docs live before the binary exists / 404 download URLs" problem. Good.
• Concurrency — constant group docs-deploy + cancel-in-progress: false is the right call given s3-sync-action runs with --delete. Serializing and never cancelling mid-sync prevents a half-deleted bucket. 👍
• Prerelease guard — !github.event.release.prerelease is correct for both event types:
  • On a prerelease publish, release.prerelease is true → job skipped.
  • On workflow_dispatch, github.event.release is null; dereferencing a property of null yields null and !null → true, so manual redeploys still run. Verified against GHA expression semantics — no accidental skip of the dispatch path.

sync-version.js regex fix — correct

The root cause is accurate: the old (?:-[\w.]+)? group was greedy and [\w.] matches the 86_64 in x86_64, so anchor-v1.1.0-x86_64- collapsed to anchor-vX.Y.Z-, stripping the arch. Dropping the optional group from the filename patterns fixes it while correctly keeping it on the tag/path portion (/download/v[\d.]+(?:-[\w.]+)?/), which legitimately needs to match prerelease tags like v1.1.0-rc.1.

I also confirmed the general-format lines (anchor-<version>-<platform>) are untouched by both regexes, since the literal <version> doesn't match v[\d.]+. Only the concrete example line is rewritten. Good.

installation.mdx / README.md — correct

• Arch-qualified filename (anchor-v1.1.0-x86_64-unknown-linux-gnu.tar.gz) now matches an actual release asset.
• The new "Deployment" section documenting release-triggered publishing and the gh workflow run docs.yml --ref stable escape hatch is a nice touch for future maintainers.

Minor, non-blocking observations

• Regex + prerelease version interaction (FYI only, not actionable): the new filename patterns assume the example version has no prerelease suffix (e.g. they'd leave a stale suffix if the example were ever anchor-v1.1.0-rc.1-x86_64-...). Since the deploy now only fires on non-prerelease publishes (!prerelease) and the docs example is always a stable release, this is consistent and fine in practice — noting it only so the coupling is on record.
• workflow_dispatch has no branch restriction: as the PR body notes, a manual dispatch from unstable would publish unstable docs. The README correctly directs operators to use --ref stable; the repository_owner == 'sigp' guard covers forks. Acceptable as documented.

Nothing to change from my side — LGTM.
• docs-deploy-on-release-publish

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 62.98%. Comparing base (1322601) to head (b2e6b9b).

Additional details and impacted files

@@            Coverage Diff            @@
##           unstable    #1210   +/-   ##
=========================================
  Coverage     62.98%   62.98%           
=========================================
  Files           162      162           
  Lines         27235    27235           
=========================================
  Hits          17154    17154           
  Misses        10081    10081           

Flag	Coverage Δ
rust	62.98% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[jnhsigmap]

low priority but I noticed no timeout on this job. Timeout is dangerous potentially with aws s3 sync --delete as we'd rather not corrupt the bucket in the case where the job gets axed as that is running. we could though add timeout-minutes: 10 or similar to steps that have external fetches like Install dependencies and Install Playwright browsers independently to stop hangs blocking our other deploys.

[shane-moore]

Good call. Added timeout-minutes: 10 to the three network-bound steps (npm ci, Playwright install, and the GitHub stats fetch in sync-version) in b2e6b9b. Left the job-level timeout off for the reason you gave: it could cancel the S3 sync mid-run. A hang now fails before the sync starts instead of holding the concurrency group for the 6h default.

[jnhsigmap]

all good otherwise

[mergify]

Queued — the merge queue status continues in this comment ↓.

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-08-05 20:49 UTC · Rule: default · triggered by rule Add outdated, ready-to-merge PRs to merge queue
• ✅ Checks passed · on draft merge queue: checking unstable (581bde1) and #1210 together #1220
• ✅ Merged — 2026-08-05 21:37 UTC · at b2e6b9bc0bb50c67339e758c6752e1c17d90caa7 · squash

This pull request spent 48 minutes 25 seconds in the queue, including 28 minutes 2 seconds running CI.

Required conditions to merge

• check-success=cli-reference-check
• check-success=run-local-testnet
• check-success=test-suite-success
• github-review-approved [🛡 GitHub repository ruleset rule unstable and release-v*]
  • ci: deploy docs site on release publish instead of every unstable push #1210
• any of [🛡 GitHub repository ruleset rule unstable and release-v*]:
  • check-success = license/cla
  • check-neutral = license/cla
  • check-skipped = license/cla