Skip to content

ci(docs): build the rossoctl.dev Moca section on every docs change - #899

Merged
pdettori merged 1 commit into
rossoctl:mainfrom
pdettori:ci/docs-site-build
Nov 18, 2026
Merged

pdettori merged 1 commit into
rossoctl:mainfrom
pdettori:ci/docs-site-build

Conversation

@pdettori

Copy link
Copy Markdown
Member

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 own npm run sync-docs with MOCA_SRC_REPO set to this checkout, then npm run build. It fails when:
    • the publish guard skips Moca (no moca/index.md after the sync);
    • the build fails (a malformed _category_.json, Markdown the site can't compile);
    • the build log reports a broken link or anchor in moca/. The site's config only warns on these, so the script turns them into failures.
  • .github/workflows/docs-site.yml runs the script on pull requests that touch docs/**, the script or the workflow, plus workflow_dispatch:
    • It checks out rossoctl/.github@main into .site and uses Node 20 with npm ci, as the site's deploy.yaml does.
    • Permissions are contents: read, with persist-credentials: false and no secrets.
    • It uploads the sync and build logs on failure.

The existing docs job in ci.yml still covers strings and relative links offline.

Testing (local, against a fresh rossoctl/.github clone)

Case Result
main's docs exit 0: "publishes and builds: 40 pages, no broken links" (16 s after npm ci)
A broken link ([broken](no-such-page.md)) exit 1: "the build reports broken links or anchors in the Moca section"
A broken anchor (brain-and-hands.md#no-such-anchor) exit 1, same message
A denylisted name (SBX9) exit 1: "the sync did not publish the Moca section"
A malformed docs/api/_category_.json exit 1: "the site build failed with this docs/"

This PR touches its own workflow file, so the new job runs on it.

Assisted-By: Claude Code

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
ingpaolodettori-dev marked this pull request as ready for review November 18, 2026 20:41
@ingpaolodettori-dev ingpaolodettori-dev added the ready-for-ai-review Request automated AI code review from clawgenti label Nov 18, 2026

@ingpaolodettori-dev ingpaolodettori-dev left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 ' ')"

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@pdettori
pdettori merged commit a64b946 into rossoctl:main Nov 18, 2026
17 checks passed
webchang added a commit to webchang/moca that referenced this pull request Nov 19, 2026
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>
@pdettori pdettori added this to the v0.11.0 milestone Nov 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ready-for-ai-review Request automated AI code review from clawgenti

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants