ci: consolidate Fern docs publishing (#155)

#### Overview

Consolidate Fern documentation validation, preview, cleanup, and publishing into the dedicated Fern Docs workflow.

- [x] I confirm this contribution is my own work, or I have the right to submit it under this project's license.
- [x] I searched existing issues and open pull requests, and this does not duplicate existing work.

#### Details

- Remove the reusable `ci_docs.yml` workflow and detach documentation checks from the package CI aggregator.
- Update `fern-docs.yml` to use the `fern` environment `FERN_TOKEN` secret for docs publishing.
- Generate stable Fern preview deployments using `pull-request-<number>` and delete the matching preview after a PR is merged.
- Update contributor, release, and Fern docs to describe the new workflow and secret model.

#### Where should the reviewer start?

Start with `.github/workflows/fern-docs.yml`, then review `.github/workflows/ci.yaml` to confirm the package CI dependency removal.

#### Related Issues: (use one of the action keywords Closes / Fixes / Resolves / Relates to)

- Relates to: none



## Summary by CodeRabbit

* **Chores**
  * Removed the separate documentation CI job; docs validation/publishing is now handled independently.
  * Switched docs publishing to use the environment-scoped FERN_TOKEN.

* **Documentation**
  * PR-based docs previews now generate unique preview IDs and are automatically cleaned up when the PR is merged.
  * Updated docs and releasing guidance to reflect the new workflow.



[![Review Change Stack](https://storage.googleapis.com/coderabbit_public_assets/review-stack-in-coderabbit-ui.svg)](https://app.coderabbit.ai/change-stack/NVIDIA/NeMo-Relay/pull/155?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack)

Authors:
  - Will Killian (https://github.com/willkill07)

Approvers:
  - Bryan Bednarski (https://github.com/bbednarski9)

URL: #155

Author: willkill07

.github/workflows/ci.yaml

@@ -138,22 +138,6 @@ jobs:
       base: ${{ needs.ci_changes.outputs.base }}
       default_branch: ${{ github.event.repository.default_branch }}
 
-  ci_docs:
-    name: Documentation
-    needs: [prepare, ci_changes, ci_check]
-    uses: ./.github/workflows/ci_docs.yml
-    if: >-
-      ${{
-        !cancelled()
-        && needs.ci_changes.result == 'success'
-        && needs.ci_check.result == 'success'
-        && needs.ci_changes.outputs.run_docs == 'true'
-      }}
-    permissions:
-      contents: read
-    secrets:
-      DOCS_FERN_TOKEN: ${{ secrets.DOCS_FERN_TOKEN }}
-
   ci_rust:
     name: Rust
     needs: [prepare, ci_changes, ci_check]
@@ -226,7 +210,6 @@ jobs:
       - prepare
       - ci_changes
       - ci_check
-      - ci_docs
       - ci_rust
       - ci_go
       - ci_node
@@ -241,7 +224,6 @@ jobs:
         env:
           CHANGES_RESULT: ${{ needs.ci_changes.result }}
           CHECK_RESULT: ${{ needs.ci_check.result }}
-          DOCS_RESULT: ${{ needs.ci_docs.result }}
           RUST_RESULT: ${{ needs.ci_rust.result }}
           GO_RESULT: ${{ needs.ci_go.result }}
           NODE_RESULT: ${{ needs.ci_node.result }}
@@ -273,8 +255,6 @@ jobs:
           require_success "Changes" "$CHANGES_RESULT"
           require_success "Check" "$CHECK_RESULT"
 
-          allow_success_or_skipped "Documentation" "$DOCS_RESULT"
-
           if [[ "$publish_packages" == "true" ]]; then
             require_success "Rust" "$RUST_RESULT"
             require_success "Node.js" "$NODE_RESULT"

.github/workflows/ci_docs.yml

@@ -10,6 +10,9 @@ on:
       - 'pull-request/**'
     tags:
       - '*'
+  pull_request:
+    types:
+      - closed
   workflow_dispatch:
     inputs:
       tag:
@@ -24,7 +27,7 @@ concurrency:
 jobs:
   changed-files:
     name: Detect docs changes
-    if: ${{ github.ref_type != 'tag' }}
+    if: ${{ github.ref_type != 'tag' && github.event_name != 'pull_request' }}
     runs-on: ubuntu-latest
     timeout-minutes: 10
     permissions:
@@ -147,7 +150,9 @@ jobs:
           FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
         run: |
           set -euo pipefail
-          if OUTPUT="$("$GITHUB_WORKSPACE/source-checkout/node_modules/.bin/fern" generate --docs --preview 2>&1)"; then
+          pr_number="${GITHUB_REF_NAME#pull-request/}"
+          preview_id="pull-request-${pr_number}"
+          if OUTPUT="$("$GITHUB_WORKSPACE/source-checkout/node_modules/.bin/fern" generate --docs --preview --id "$preview_id" 2>&1)"; then
             fern_exit=0
           else
             fern_exit=$?
@@ -172,7 +177,59 @@ jobs:
           gh pr comment "https://github.com/${{ github.repository }}/pull/${pr_number}" \
             --edit-last \
             --create-if-none \
-            --body "Fern docs preview: ${{ steps.preview.outputs.url }}/dev"
+            --body "Fern docs preview: ${{ steps.preview.outputs.url }}"
+
+  cleanup-preview-docs:
+    name: Clean up docs preview
+    if: >-
+      ${{
+        github.event_name == 'pull_request'
+        && github.event.action == 'closed'
+        && github.event.pull_request.merged == true
+      }}
+    runs-on: ubuntu-latest
+    environment: fern
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    env:
+      UV_PYTHON_DOWNLOADS: never
+    steps:
+      - name: Checkout source branch
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          ref: ${{ github.event.pull_request.base.ref }}
+          path: source-checkout
+          fetch-depth: 1
+          persist-credentials: false
+
+      - name: Load CI tool versions
+        id: ci-config
+        uses: ./source-checkout/.github/actions/load-ci-tool-versions
+
+      - name: Setup Node.js
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6
+        with:
+          node-version: ${{ steps.ci-config.outputs.node_version }}
+          package-manager-cache: false
+
+      - name: Install Fern CLI
+        working-directory: source-checkout
+        run: |
+          set -euo pipefail
+          npm ci --ignore-scripts
+
+      - name: Delete preview deployment
+        working-directory: source-checkout/fern
+        env:
+          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          set -euo pipefail
+          preview_id="pull-request-${PR_NUMBER}"
+          echo "Deleting Fern docs preview: ${preview_id}"
+          "$GITHUB_WORKSPACE/source-checkout/node_modules/.bin/fern" docs preview delete --id "$preview_id" \
+            || echo "Fern preview deletion returned non-zero; it may already be deleted."
 
   publish-dev-docs:
     name: Publish dev docs
@@ -186,6 +243,7 @@ jobs:
         )
       }}
     runs-on: ubuntu-latest
+    environment: fern
     timeout-minutes: 60
     permissions:
       contents: write
@@ -253,7 +311,7 @@ jobs:
         working-directory: source-checkout
         env:
           NEMO_RELAY_DOCS_DEPS_READY: "1"
-          FERN_TOKEN: ${{ secrets.DOCS_FERN_TOKEN }}
+          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
         run: just docs
 
       - name: Checkout docs website branch
@@ -302,7 +360,7 @@ jobs:
         if: ${{ steps.changes.outputs.has_changes == 'true' }}
         working-directory: docs-checkout/fern
         env:
-          FERN_TOKEN: ${{ secrets.DOCS_FERN_TOKEN }}
+          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
         run: |
           "$GITHUB_WORKSPACE/source-checkout/node_modules/.bin/fern" generate --docs
 
@@ -314,6 +372,7 @@ jobs:
         || (github.event_name == 'workflow_dispatch' && inputs.tag != '' && inputs.tag != null)
       }}
     runs-on: ubuntu-latest
+    environment: fern
     timeout-minutes: 30
     permissions:
       contents: write
@@ -403,6 +462,6 @@ jobs:
       - name: Publish docs
         working-directory: docs-checkout/fern
         env:
-          FERN_TOKEN: ${{ secrets.DOCS_FERN_TOKEN }}
+          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
         run: |
           "$GITHUB_WORKSPACE/source-checkout/node_modules/.bin/fern" generate --docs

.github/workflows/fern-docs.yml

@@ -254,8 +254,8 @@ The workflow boundary is split intentionally:
 
 - The language-specific reusable workflows produce publishable package artifacts
   after their tests pass.
-- [`.github/workflows/ci_docs.yml`](.github/workflows/ci_docs.yml) validates the
-  Fern documentation.
+- [`.github/workflows/fern-docs.yml`](.github/workflows/fern-docs.yml) validates
+  and publishes Fern documentation independently from package CI.
 - [`.github/workflows/ci.yaml`](.github/workflows/ci.yaml) owns all crates.io,
   PyPI, and npm publication decisions and credentials.
 - This layout also satisfies the official `pypa/gh-action-pypi-publish`

RELEASING.md

@@ -104,16 +104,17 @@ on `main` in `docs/` and `fern/`. The generated Fern content on
 `.gitignore`, `README.md`, and `.github/workflows/publish-fern-docs.yml` are
 branch-local maintenance files and can be updated directly on `docs-website`.
 
-The Fern workflow uses `DOCS_FERN_TOKEN` as the repository secret. Pull-request
-branches under `pull-request/**` get Fern previews when docs change. Pushes to
-`main` sync the generated `fern/pages-dev/` layout to `docs-website` and publish
-the dev docs. Raw SemVer tags such as `0.1.0`, `0.1.0-beta.1`, and `0.1.0-rc.1`
-create public docs versions displayed with a leading `v`. Prerelease indicators
-are stripped from the public docs version path, so `0.1.0-beta.1`,
-`0.1.0-rc.1`, and `0.1.0` all target `v0.1.0`. Stable tags use
-`availability: stable` and update the default `Latest` version. Beta and
-release-candidate tags use `availability: beta`, replace the same base version
-snapshot, and do not update `Latest`. Alpha tags are not published.
+The Fern workflow uses the `FERN_TOKEN` GitHub environment secret from the
+`fern` environment. Pull-request branches under `pull-request/**` get Fern
+previews when docs change, and merged pull requests clean up their preview
+deployment. Pushes to `main` sync the generated `fern/pages-dev/` layout to
+`docs-website` and publish the dev docs. Raw SemVer tags such as `0.1.0`,
+`0.1.0-beta.1`, and `0.1.0-rc.1` create public docs versions displayed with a
+leading `v`. Prerelease indicators are stripped from the public docs version
+path, so `0.1.0-beta.1`, `0.1.0-rc.1`, and `0.1.0` all target `v0.1.0`. Stable
+tags use `availability: stable` and update the default `Latest` version. Beta
+and release-candidate tags use `availability: beta`, replace the same base
+version snapshot, and do not update `Latest`. Alpha tags are not published.
 
 The branch sync and version snapshot logic lives in
 `scripts/docs/sync_fern_docs_branch.py`.

docs/contribute/testing-and-docs.mdx

@@ -46,11 +46,12 @@ layout can be validated outside GitHub Actions.
 
 ## Publishing
 
-The Fern publish workflow uses the GitHub secret `DOCS_FERN_TOKEN` and passes it
-to the Fern CLI as `FERN_TOKEN`.
+The Fern publish workflow uses the `FERN_TOKEN` GitHub environment secret from
+the `fern` environment and passes it to the Fern CLI as `FERN_TOKEN`.
 
-- Pushes to `pull-request/**` that affect docs generate a Fern preview and add
-  the preview URL to the pull request.
+- Pushes to `pull-request/**` that affect docs generate a stable Fern preview
+  and add the preview URL to the pull request. When the pull request is merged,
+  the workflow deletes the matching preview deployment.
 - Pushes to `main` that affect docs regenerate API reference pages, sync
   `docs-website`, and publish the dev docs.
 - Raw SemVer tags such as `0.1.0`, `0.1.0-beta.1`, and `0.1.0-rc.1` create or