fix(ci): tolerate absent Fern previews

[senthilr-nv]

Summary

Post-merge docs cleanup now treats Fern's Domain not registered response as an already-absent preview. Other Fern deletion failures continue to fail the workflow.

Changes

• Capture Fern preview deletion output and accept only the exact missing-domain result.
• Keep authentication, network, and other Fern failures blocking.
• Add regression coverage for an absent preview and a non-absence deletion error.
• Record the escaped-defect cause: cleanup inferred a preview from the merged PR association, while fork PRs can validate docs without creating a preview. The previous test covered only successful deletion URL construction.

Type of Change

• 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

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification: This changes post-merge CI cleanup only. It does not change user-facing behavior, commands, configuration, schemas, or supported product contracts.
• 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:

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: no-docs-needed
• Evidence: The change only makes post-merge Fern preview deletion idempotent for an absent preview. It does not change user-facing behavior, CLI output, configuration, schemas, or supported product contracts.
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit:
• Station profile/scenario:
• Result:
• Supporting evidence:

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run check:diff passed when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — command/result or justification: npx vitest run test/docs-publish-staging-workflow.test.ts — 1 file and 4 tests passed.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result:
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Senthil Ravichandran senthilr@nvidia.com

Summary by CodeRabbit

• Bug Fixes

  • Staging documentation preview cleanup now continues when a preview domain is already unregistered.
  • Other deletion errors still stop the workflow and display the relevant error details.

• Tests

  • Added coverage for handling expected preview deletion errors and preserving failures for unexpected errors.

[coderabbitai]

📝 Walkthrough

Walkthrough

The staging documentation workflow now captures Fern preview deletion output, continues past “Domain not registered” errors, and fails on other errors. Tests cover Fern error output, exit status, and temporary mock cleanup.

Changes

Staging preview cleanup

Layer / File(s)	Summary
Preview deletion handling and validation .github/workflows/docs-publish-staging.yaml, test/docs-publish-staging-workflow.test.ts	The workflow handles domain-registration failures with notices, reports other failures, prints successful output, and adds parameterized tests for these error scenarios.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers: miyoungc

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main CI change: tolerating absent Fern previews during cleanup.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 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-staging.yaml:
- Around line 133-136: Update the cleanup check around the preview deletion
command to compare the entire delete_output value against the exact “Domain not
registered” response, rather than matching an individual line with grep.
Preserve the existing notice and continue behavior only for an exact response,
and add a regression case covering mixed output such as “Domain not registered”
plus “Authentication failed.”

🪄 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: fd534622-48c8-4e40-a402-41fe2bb0924b

📥 Commits

Reviewing files that changed from the base of the PR and between ec59e47 and 1add6cc.

📒 Files selected for processing (2)

• .github/workflows/docs-publish-staging.yaml
• test/docs-publish-staging-workflow.test.ts

[coderabbitai]

🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Match the complete Fern response, not any matching line.

grep -Fxq succeeds if any individual line matches, so a response such as Domain not registered\nAuthentication failed would incorrectly allow cleanup to pass. Compare delete_output as a whole and add a mixed-output regression case.

Proposed fix

-              if grep -Fxq "Domain not registered" <<< "$delete_output"; then
+              if [[ "$delete_output" == "Domain not registered" ]]; then

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	if ! delete_output=$(npx --yes "fern-api@${FERN_VERSION}" docs preview delete "$preview_url" 2>&1); then
	if grep -Fxq "Domain not registered" <<< "$delete_output"; then
	echo "::notice::Fern preview ${preview_id} does not exist."
	continue
	if ! delete_output=$(npx --yes "fern-api@${FERN_VERSION}" docs preview delete "$preview_url" 2>&1); then
	if [[ "$delete_output" == "Domain not registered" ]]; then
	echo "::notice::Fern preview ${preview_id} does not exist."
	continue

🤖 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 133 - 136, Update
the cleanup check around the preview deletion command to compare the entire
delete_output value against the exact “Domain not registered” response, rather
than matching an individual line with grep. Preserve the existing notice and
continue behavior only for an exact response, and add a regression case covering
mixed output such as “Domain not registered” plus “Authentication failed.”

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high confidence
Next action: Review the warnings below.
Findings: 0 blockers · 1 warning · 0 suggestions
Status: Canonical ledger: 0 blocker(s), 1 warning(s), 0 suggestion(s).

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 1 warning · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings differ; normalized E2E selections differ; Nemotron reported the same number of blockers, 1 fewer warning, the same number of suggestions.

Nemotron output stays in workflow artifacts and does not change the assessment above.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: None

1 optional E2E recommendation

• docs-validation

1 warning · 0 suggestions

Warnings

Warnings do not block.

PRA-1 Warning — Document the missing-preview recovery boundary

• Location: .github/workflows/docs-publish-staging.yaml:133
• Category: correctness
• Problem: The workflow now treats Fern's `Domain not registered` failure as successful cleanup, but it does not identify the state that removes the preview or why this workflow cannot prevent that state.
• Impact: The workflow can hide an unclassified absent-preview condition as expected cleanup, so maintainers cannot distinguish the intended race from an unexpected source-state regression.
• Recommendation: Document the producer of the missing-preview state and why deletion must tolerate it here. Add a removal condition or replace the exception when the producer no longer creates this state.
• Verification: Inspect the preview creation and deletion workflows for the path that can remove a Fern preview before this job calls `docs preview delete`.
• Test coverage: Add a workflow-contract test that documents the named producer scenario and verifies only its absent-preview response is tolerated.
• Evidence: `.github/workflows/docs-publish-staging.yaml:133-140` catches a nonzero Fern exit and continues when its captured output contains the exact line `Domain not registered`. The changed workflow and test contain no explanation of where a preview can disappear before cleanup or why that source cannot be fixed in this PR. The added test covers the tolerated response but does not identify or exercise the state producer. `.github/workflows/docs-publish-staging.yaml:133-140` continues after an exact `Domain not registered` failure. The checked-in workflow and test do not identify the state producer, why it cannot be fixed here, or a removal condition.

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.