Repository navigation
ci(docs): publish Fern docs from staging and releases - #6157
Merged
Merged
Conversation
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughThis PR updates preview generation to target a configured staging Fern instance, adds a main-branch staging publish workflow with preview cleanup, adds a tag-triggered public publish workflow, and registers an additional staging docs instance. ChangesDocs Publishing and Preview Configuration
Estimated code review effort: 4 (Complex) | ~45 minutes Sequence Diagram(s)sequenceDiagram
participant GitHubActions as GitHub Actions
participant NpmScripts as npm scripts
participant FernCLI as fern-api CLI
participant FernDocs as Fern Docs Instance
participant GitHubAPI as GitHub API
GitHubActions->>NpmScripts: npm run docs:sync-agent-variants
GitHubActions->>NpmScripts: npm run docs
GitHubActions->>FernCLI: generate --docs --instance staging
FernCLI->>FernDocs: publish staging docs
GitHubActions->>GitHubAPI: find PRs for commit SHA
GitHubActions->>FernCLI: docs preview delete --id pr-<number>
FernCLI->>FernDocs: delete preview
GitHubActions->>GitHubActions: verify tag commit is reachable from origin/main
GitHubActions->>FernCLI: generate --docs --instance public
FernCLI->>FernDocs: publish public docs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Contributor
Code Coverage OverviewLanguages: TypeScript TypeScript / code-coverage/pluginThe overall coverage in the Show a code coverage summary of the most covered files.
TypeScript / code-coverage/cliThe overall coverage in the Show a code coverage summary of the most covered files.
Updated |
Contributor
E2E Advisor RecommendationRequired E2E: None Full advisor summaryE2E Recommendation AdvisorBase: Required E2E
Optional E2E
New E2E recommendations
|
Contributor
E2E Target RecommendationRequired E2E targets: None Full E2E target advisor summaryE2E Target AdvisorBase: Required E2E targets
Optional E2E targets
Relevant changed files
|
Contributor
|
🌿 Preview your docs: https://nvidia-preview-pr-6157.docs.buildwithfern.com/nemoclaw |
Contributor
PR Review Advisor — Changes requestedMerge posture: Do not merge yet Action checklist
Findings index
Review findings by urgency: 0 required fixes, 5 items to resolve/justify, 0 in-scope improvements
|
Contributor
PR Review Advisor (Nemotron Ultra) — BlockedMerge posture: Do not merge until addressed Action checklist
Findings index
🚨 Required before mergeAddress these before merging unless a maintainer explicitly overrides the advisor with rationale.
|
miyoungc
added
area: ci
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.github/workflows/docs-publish-public.yaml:
- Around line 26-27: The checkout step in the docs publish workflow is still
persisting the GitHub token by default, which is unnecessary here. Update the
existing actions/checkout usage in the checkout step to explicitly disable
credential persistence, matching the staging workflow behavior, so later steps
cannot read the token. Keep the change scoped to the Checkout repository step in
the workflow and preserve the current checkout action reference.
- Around line 29-32: The Setup Node.js step in the docs-publish-public workflow
is relying on actions/setup-node@v6 default package-manager caching, which
should be turned off for this privileged publish job. Update the Setup Node.js
configuration to explicitly disable automatic npm cache detection by setting
package-manager-cache to false in the workflow step. Keep the change scoped to
the Setup Node.js action in docs-publish-public so the release-publish flow no
longer restores potentially poisoned cache state while using FERN_TOKEN.
In @.github/workflows/docs-publish-staging.yaml:
- Around line 32-33: Disable token persistence in the Checkout repository step
by updating the actions/checkout usage in the docs-publish-staging workflow so
the repository is checked out without writing credentials to local git config.
Keep the existing checkout step, but set the checkout action’s
credential-persistence option to false so later npm ci and npm run steps cannot
read the token from the job workspace.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 0b0ea518-1552-4ef9-8189-234395880f24
📒 Files selected for processing (4)
.github/workflows/docs-preview-pr.yaml.github/workflows/docs-publish-public.yaml.github/workflows/docs-publish-staging.yamlfern/docs.yml
Contributor
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
scripts/checks/docs-publish-workflows.ts (1)
1-246: 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick winAdd focused tests for this guardrail.
No test coverage is provided for
docs-publish-workflows.ts. The pure helper functions (assertPinnedActions,assertFernVersionSource,assertPublishSteps, etc.) are straightforward to unit test with small in-memory YAML fixtures covering both a passing case and known-bad cases (missing pin, wrong instance, guard-after-publish ordering).Do you want me to draft a test suite covering detection and false-positive scenarios for these assertions?
As per path instructions, "Require focused tests for both detection and false-positive behavior."
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@scripts/checks/docs-publish-workflows.ts` around lines 1 - 246, Add focused unit tests for docs-publish-workflows.ts, covering the pure helpers like assertPinnedActions, assertFernVersionSource, assertPublishSteps, assertPreviewWorkflow, assertStagingWorkflow, and assertPublicWorkflow with small in-memory YAML fixtures. Include both passing cases and negative cases such as unpinned actions, wrong Fern instance/env, missing config-based FERN_VERSION usage, and guard-after-publish ordering, and verify false-positive scenarios where valid fixtures produce no errors.Source: Path instructions
🧹 Nitpick comments (1)
scripts/checks/docs-publish-workflows.ts (1)
163-168: 🔒 Security & Privacy | 🔵 Trivial | ⚡ Quick winConsider enforcing
persist-credentials: falsehere too.This check already inspects the checkout step's
withblock forfetch-depth. Since the workflow it validates is missingpersist-credentials: false(flagged separately by zizmor), extending this assertion would deterministically prevent that regression going forward instead of relying on a linter catching it each time.♻️ Proposed addition
const checkout = workflowSteps(workflow, "publish").find((step) => stringValue(step.uses).startsWith("actions/checkout@"), ); if (asRecord(checkout?.with)["fetch-depth"] !== 0) { errors.push(`${workflow.path}: public publish checkout must use fetch-depth: 0`); } + if (asRecord(checkout?.with)["persist-credentials"] !== false) { + errors.push(`${workflow.path}: public publish checkout must disable persist-credentials`); + }As per path instructions, "Enforce objective invariants with deterministic code."
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@scripts/checks/docs-publish-workflows.ts` around lines 163 - 168, The publish-workflow checkout validation in docs-publish-workflows.ts only enforces fetch-depth, so extend the existing checkout step check in the publish workflow to also require persist-credentials to be false. Update the logic around workflowSteps(workflow, "publish") and the checkout step’s with block so both invariants are asserted together, and keep reporting through the same errors.push path when either setting is missing or incorrect.Source: Path instructions
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@scripts/checks/docs-publish-workflows.ts`:
- Around line 1-246: Add focused unit tests for docs-publish-workflows.ts,
covering the pure helpers like assertPinnedActions, assertFernVersionSource,
assertPublishSteps, assertPreviewWorkflow, assertStagingWorkflow, and
assertPublicWorkflow with small in-memory YAML fixtures. Include both passing
cases and negative cases such as unpinned actions, wrong Fern instance/env,
missing config-based FERN_VERSION usage, and guard-after-publish ordering, and
verify false-positive scenarios where valid fixtures produce no errors.
---
Nitpick comments:
In `@scripts/checks/docs-publish-workflows.ts`:
- Around line 163-168: The publish-workflow checkout validation in
docs-publish-workflows.ts only enforces fetch-depth, so extend the existing
checkout step check in the publish workflow to also require persist-credentials
to be false. Update the logic around workflowSteps(workflow, "publish") and the
checkout step’s with block so both invariants are asserted together, and keep
reporting through the same errors.push path when either setting is missing or
incorrect.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 1a89a133-95ea-4284-85a7-9e3b3c53d081
📒 Files selected for processing (4)
.github/workflows/docs-publish-public.yaml.github/workflows/docs-publish-staging.yamlscripts/checks/docs-publish-workflows.tsscripts/checks/run.ts
🚧 Files skipped from review as they are similar to previous changes (1)
- .github/workflows/docs-publish-staging.yaml
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (1)
.github/workflows/docs-publish-staging.yaml (1)
67-98: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winConsolidate the two identical
gh apicalls.The step calls
gh api repos/${GH_REPO}/commits/${COMMIT_SHA}/pullstwice — once to buildpreview_ids(lines 78-81), once to buildpr_numbers(lines 84-88) — doubling API usage for the same data.♻️ Proposed consolidation
- { - echo "preview_ids<<EOF" - gh api "repos/${GH_REPO}/commits/${COMMIT_SHA}/pulls" \ - -H "Accept: application/vnd.github+json" \ - --jq '.[] | "pr-\(.number)"' - echo "EOF" - } >> "$GITHUB_OUTPUT" - - mapfile -t pr_numbers < <( - gh api "repos/${GH_REPO}/commits/${COMMIT_SHA}/pulls" \ - -H "Accept: application/vnd.github+json" \ - --jq '.[].number' - ) + mapfile -t pr_numbers < <( + gh api "repos/${GH_REPO}/commits/${COMMIT_SHA}/pulls" \ + -H "Accept: application/vnd.github+json" \ + --jq '.[].number' + ) + { + echo "preview_ids<<EOF" + printf 'pr-%s\n' "${pr_numbers[@]}" + echo "EOF" + } >> "$GITHUB_OUTPUT"🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.github/workflows/docs-publish-staging.yaml around lines 67 - 98, The “Find merged PR previews” step is calling the same gh api endpoint twice to fetch commit-associated PRs. Consolidate this in the workflow by using a single gh api invocation in the run block, storing its output once, and reusing it to derive both preview_ids and pr_numbers in the same step. Keep the logic in the existing “Find merged PR previews” step and preserve the has_previews guard and output formatting.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In @.github/workflows/docs-publish-staging.yaml:
- Around line 67-98: The “Find merged PR previews” step is calling the same gh
api endpoint twice to fetch commit-associated PRs. Consolidate this in the
workflow by using a single gh api invocation in the run block, storing its
output once, and reusing it to derive both preview_ids and pr_numbers in the
same step. Keep the logic in the existing “Find merged PR previews” step and
preserve the has_previews guard and output formatting.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 6efe04a5-0a2e-4f47-b385-b9134c6a9964
📒 Files selected for processing (1)
.github/workflows/docs-publish-staging.yaml
Collaborator
Author
|
Thanks for the automated review. I am not planning to incorporate the remaining PR Advisor recommendations unless a human reviewer feels strongly otherwise. Rationale:
If reviewers think any of the remaining recommendations should be required for this PR, please say so and I will adjust. |
cv
approved these changes
Jul 2, 2026
Hadar301
pushed a commit
to Hadar301/NemoClaw-OpenShift
that referenced
this pull request
Jul 12, 2026
<!-- markdownlint-disable MD041 --> ## Summary This PR adds Fern publishing automation for NemoClaw docs so merged docs changes publish to staging and release tags publish to the public instance. It points PR previews at the staging Fern instance, keeps the Fern CLI version sourced from `fern/fern.config.json`, and removes PR preview deployments after staging publish succeeds. ## Changes - Add a staging Fern instance in `fern/docs.yml`. - Add `Docs / Publish Staging` for `main` pushes that touch docs, Fern config, or docs build inputs. - Add `Docs / Publish Public` for `v*.*.*` release tag pushes. - Run `npm run docs:sync-agent-variants` and `npm run docs` before both Fern publish commands. - Point PR preview generation at the staging instance with `--instance`, disable checkout credential persistence, and validate the extracted Fern preview URL before posting it. - Delete merged PR Fern previews after staging publish succeeds with `fern docs preview delete --id pr-<number>`. - Guard public publishing with the `docs-public` environment and an ancestry check that runs immediately after checkout and requires release tag commits to be reachable from `origin/main` before any npm/Fern commands. - Disable checkout credential persistence for staging and public publish jobs; disable setup-node package-manager caching for the public publish job. - Keep workflow validation lightweight through existing YAML checks, hooks, and CI rather than adding a bespoke static checker. ## Type of Change - [x] Code change (feature, bug fix, or refactor) - [ ] Code change with doc updates - [ ] Doc only (prose changes, no code sample modifications) - [ ] Doc only (includes code sample changes) ## Quality Gates <!-- Check all that apply. For any "covered by existing tests", "not applicable", or waiver entry, add a brief justification on the same line or in the Changes section. --> - [ ] Tests added or updated for changed behavior - [ ] Existing tests cover changed behavior — justification: - [x] Tests not applicable — justification: CI/Fern publishing configuration only; no runtime product code paths changed. The workflows are covered by existing YAML validation, pre-commit/pre-push hooks, and CI execution on this PR. - [ ] Docs updated for user-facing behavior changes - [x] Docs not applicable — justification: This changes repository publishing automation, not user-facing product behavior or docs content. - [ ] Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging) - [ ] Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: - [ ] Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue: ## Verification <!-- Check each item you ran and confirmed. Leave unchecked items you skipped. Doc-only changes do not require npm test unless you ran it. --> - [x] PR description includes the DCO sign-off declaration and every commit appears as `Verified` in GitHub - [x] Git hooks passed during commit and push, or `npx prek run --from-ref main --to-ref HEAD` passes - [ ] Targeted tests pass for changed behavior - [ ] Full `npm test` passes (broad runtime changes only) - [x] Quality Gates section completed with required justifications or waivers - [x] No secrets, API keys, or credentials committed - [ ] `npm run docs` builds without warnings (doc changes only) - [ ] Doc pages follow the [style guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md) (doc changes only) - [ ] New doc pages include SPDX header and frontmatter (new pages only) Additional verification: - `npm ci --ignore-scripts` - `npm run docs:sync-agent-variants` - `npm run docs` passed with 0 Fern errors; existing Fern warnings remain for the published-redirects network check and light-mode accent contrast. - `FERN_VERSION=$(node -p "require('./fern/fern.config.json').version") && cd fern && npx --yes "fern-api@${FERN_VERSION}" check --warnings` - `npm run typecheck:cli` - `npm run build:cli` - Pre-commit hooks passed during commits, including YAML checks, repository checks, and secret scanning. - Pre-push hooks passed after pushes. - `git diff --check` - ReadLints reported no issues for changed workflow/config files. - Manual staging publish succeeded: https://nvidia-nemoclaw-staging.docs.buildwithfern.com/nemoclaw, deployment `019f2071-e6b7-72d2-be92-21bf324c96c1`. Reviewer notes: - `fern/fern.config.json` is the intended single source of truth for the Fern CLI version, so this PR intentionally does not duplicate that value in workflow YAML. - A bespoke static workflow checker was removed to avoid adding maintenance-heavy validation for a small publishing workflow change. - Checkout v7 updates are left to the existing dependency/update PR rather than mixing action-version churn into this PR. --- <!-- DCO sign-off is required in this PR description, and every commit must appear as Verified in GitHub. Run: git config user.name && git config user.email --> Signed-off-by: Miyoung Choi <miyoungc@nvidia.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds Fern publishing automation for NemoClaw docs so merged docs changes publish to staging and release tags publish to the public instance.
It points PR previews at the staging Fern instance, keeps the Fern CLI version sourced from
fern/fern.config.json, and removes PR preview deployments after staging publish succeeds.Changes
fern/docs.yml.Docs / Publish Stagingformainpushes that touch docs, Fern config, or docs build inputs.Docs / Publish Publicforv*.*.*release tag pushes.npm run docs:sync-agent-variantsandnpm run docsbefore both Fern publish commands.--instance, disable checkout credential persistence, and validate the extracted Fern preview URL before posting it.fern docs preview delete --id pr-<number>.docs-publicenvironment and an ancestry check that runs immediately after checkout and requires release tag commits to be reachable fromorigin/mainbefore any npm/Fern commands.Type of Change
Quality Gates
Verification
Verifiedin GitHubnpx prek run --from-ref main --to-ref HEADpassesnpm testpasses (broad runtime changes only)npm run docsbuilds without warnings (doc changes only)Additional verification:
npm ci --ignore-scriptsnpm run docs:sync-agent-variantsnpm run docspassed with 0 Fern errors; existing Fern warnings remain for the published-redirects network check and light-mode accent contrast.FERN_VERSION=$(node -p "require('./fern/fern.config.json').version") && cd fern && npx --yes "fern-api@${FERN_VERSION}" check --warningsnpm run typecheck:clinpm run build:cligit diff --check019f2071-e6b7-72d2-be92-21bf324c96c1.Reviewer notes:
fern/fern.config.jsonis the intended single source of truth for the Fern CLI version, so this PR intentionally does not duplicate that value in workflow YAML.Signed-off-by: Miyoung Choi miyoungc@nvidia.com