Repository navigation
ci(docs): build the rossoctl.dev Moca section on every docs change - #899
Conversation
scripts/check-docs-site.sh (make check-docs-site SITE_DIR=..., and the new Docs site workflow on pull requests touching docs/) runs the rossoctl/.github sync and build against this checkout, as the site's deploy does, and fails when the Moca section would be held back by the publish guard, would not build, or would carry a broken link or anchor (the site only warns on those). The docs job in ci.yml checks strings and relative links offline; this checks the site itself: a malformed _category_.json, Markdown the site cannot build, or an anchor that breaks only after the sync rewrites the tree. Tested locally on main's docs (40 pages, 16 s) and on a broken link, a broken anchor, a denylisted name and a malformed _category_.json, each failing with its own message. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Paolo Dettori <dettori@us.ibm.com>
ingpaolodettori-dev
left a comment
There was a problem hiding this comment.
Review
Verified against rossoctl/.github @ main: npm run sync-docs honours MOCA_SRC_REPO; the publish guard's skip condition is exactly "no moca/index.md"; the config has onBrokenLinks: 'warn' and markdown.hooks.onBrokenMarkdownLinks: 'warn'; the output dir is the default build/; deploy.yaml uses Node 20 + npm ci. The script and workflow mirror the deploy as described.
I also ran the new gate itself locally against a fresh site clone (npm ci + sync-docs + build), injecting one defect at a time:
- broken anchor on
docs/glossary.md->- Broken anchor on source page path = /moca/glossary:caught, exit 1 - broken path on
docs/index.md->- Broken link on source page path = /moca/:caught, exit 1
Clean docs pass in CI on this PR (job "Build the rossoctl.dev Moca section", 1m18s).
Workflow hygiene: actions pinned to SHAs, contents: read, persist-credentials: false on both checkouts, no secrets, pull_request (not pull_request_target); the script uses set -euo pipefail. DCO signed; all 16 checks green.
Author: pdettori (MEMBER — maintainer)
Areas reviewed: CI/GitHub Actions, Shell, Makefile; cross-repo check against rossoctl/.github
Agent/IDE config (.claude/.vscode): none
Commits: 1 commit, all signed-off: yes
CI status: passing
Two non-blocking nits inline.
| persist-credentials: false | ||
|
|
||
| # Node 20 and npm ci, as rossoctl/.github's deploy.yaml does. | ||
| - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v6 |
There was a problem hiding this comment.
nit: the comment says # v6, but 949feb2413d6… is the v7.1.0 tag (the v6 tag peels to 2499707…). The same comment sits on the same SHA in ci.yml:31 and mocactl-release.yml:38, so it may be a repo-wide stale label — still worth correcting here so the pin is identifiable.
| echo "docs-site: the build reports broken links or anchors in the Moca section" >&2 | ||
| exit 1 | ||
| fi | ||
| pages="$(find "$site/build/moca" -name index.html | wc -l | tr -d ' ')" |
There was a problem hiding this comment.
suggestion: find runs under pipefail, so if build/moca is missing (e.g. the site changes outDir/routeBasePath, or a build that skips the Moca instance) the script dies on find's error with no explanation; and a present-but-empty build/moca would print 0 pages, no broken links and pass. Consider an explicit [[ -d "$site/build/moca" ]] guard plus a pages > 0 assertion.
Brings 15 upstream merges since 2eb0219, among them the R2 host sampler in its reviewed form (rossoctl#904), the workspace-reset marker (rossoctl#895), turn budgets and cancel (rossoctl#856), the egress allow-all option (rossoctl#886), the sbx installer token (rossoctl#888), and the docs site with the product-name prose (rossoctl#884, rossoctl#885, rossoctl#899). One conflict, deploy/sbx/template-onboarding/README.md: upstream's product-name wording for the deploy/sbx table, keeping the fork's mint-login.sh row. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Rong Chang <rong@us.ibm.com>
Summary
This adds a CI job that builds the real rossoctl.dev site with a PR's
docs/as its Moca section, the same way the site's deploy does. It fails if the Moca section would be held back, would not build, or would carry a broken link or anchor. This is the follow-up offered in the rossoctl/.github#227 review: the publish denylist only checks for banned strings, so a real build is the stronger gate.scripts/check-docs-site.sh <site-dir>(make check-docs-site SITE_DIR=…) runs the site's ownnpm run sync-docswithMOCA_SRC_REPOset to this checkout, thennpm run build. It fails when:moca/index.mdafter the sync);_category_.json, Markdown the site can't compile);moca/. The site's config only warns on these, so the script turns them into failures..github/workflows/docs-site.ymlruns the script on pull requests that touchdocs/**, the script or the workflow, plusworkflow_dispatch:rossoctl/.github@maininto.siteand uses Node 20 withnpm ci, as the site'sdeploy.yamldoes.contents: read, withpersist-credentials: falseand no secrets.The existing
docsjob inci.ymlstill covers strings and relative links offline.Testing (local, against a fresh
rossoctl/.githubclone)main's docsnpm ci)[broken](no-such-page.md))brain-and-hands.md#no-such-anchor)SBX9)docs/api/_category_.jsonThis PR touches its own workflow file, so the new job runs on it.
Assisted-By: Claude Code