[doc-only] Fix backport release checks and add release dry-run (#2161)

* Check release notes for planned backports

Require mainline cuda-bindings and cuda-python releases to explicitly declare a planned backport tag or mark it not planned. Keep actual backport releases unblocked while surfacing missing notes as warnings, and preserve docs builds for older tags that still use ci/versions.json.

* Add dry-run release workflow mode

Validate release docs, archives, and wheels without publishing to GitHub Releases, GitHub Pages, TestPyPI, or PyPI.

* Allow dry-run docs branch deployment

Add an explicit dry-run docs branch input so release dry-runs can optionally write generated docs to a seeded non-production branch while keeping artifact-only dry-runs as the default.

* Default release workflow dispatches to dry-run

Make dry-run the first and default release action so production publishing must be deliberately selected for manual release workflow runs.

* Constrain dry-run docs deploy branches

Require optional dry-run docs deployments to target a non-production gh-pages-* branch so manual release dry-runs cannot accidentally publish docs to production or source branches.

* CI: fetch tags for release dry-run validation

PR #2177 made the release workflow checkout shallow, so the dry-run tag validation now needs tags fetched explicitly while keeping history shallow.

* CI: document release dry-run retest matrix

Add workflow-local guidance for validating non-trivial release workflow changes with focused dry-run coverage.

Author: rwgk

.github/workflows/build-docs.yml

@@ -33,6 +33,16 @@ on:
         required: false
         default: false
         type: boolean
+      deploy-docs:
+        description: "Deploy generated docs to GitHub Pages or preview branches"
+        required: false
+        default: true
+        type: boolean
+      docs-branch:
+        description: "Branch that receives deployed docs"
+        required: false
+        default: "gh-pages"
+        type: string
 
 jobs:
   build:
@@ -52,7 +62,14 @@ jobs:
 
       - name: Read build CTK version
         run: |
-          BUILD_CTK_VER=$(yq '.cuda.build.version' ci/versions.yml)
+          if [[ -f ci/versions.yml ]]; then
+            BUILD_CTK_VER=$(yq '.cuda.build.version' ci/versions.yml)
+          elif [[ -f ci/versions.json ]]; then
+            BUILD_CTK_VER=$(jq -r '.cuda.build.version' ci/versions.json)
+          else
+            echo "error: cannot find ci/versions.yml or ci/versions.json" >&2
+            exit 1
+          fi
           if [[ ! "${BUILD_CTK_VER}" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
             echo "error: derived CTK build version ${BUILD_CTK_VER} does not match MAJOR.MINOR.MICRO" >&2
             exit 1
@@ -305,25 +322,35 @@ jobs:
           key: ${{ steps.restore-lychee-cache.outputs.cache-primary-key }}
 
       - name: Upload docs GitHub Pages artifact
+        if: ${{ inputs.deploy-docs }}
         uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9  # v5.0.0
         with:
           path: artifacts/
           retention-days: 3
 
+      - name: Upload dry-run docs artifact
+        if: ${{ !inputs.deploy-docs || (inputs.is-release && inputs.docs-branch != 'gh-pages') }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: release-docs-dry-run-${{ inputs.component }}-${{ inputs.git-tag }}
+          path: artifacts/docs/
+          retention-days: 3
+
       - name: Deploy or clean up doc preview
-        if: ${{ !inputs.is-release }}
+        if: ${{ inputs.deploy-docs && !inputs.is-release }}
         uses: ./.github/actions/doc_preview
         with:
           source-folder: ${{ (github.ref_name != 'main' && 'artifacts/docs') ||
                               'artifacts/empty_docs' }}
           pr-number: ${{ env.PR_NUMBER }}
 
       - name: Deploy doc update
-        if: ${{ github.ref_name == 'main' || inputs.is-release }}
+        if: ${{ inputs.deploy-docs && (github.ref_name == 'main' || inputs.is-release) }}
         uses: JamesIves/github-pages-deploy-action@d92aa235d04922e8f08b40ce78cc5442fcfbfa2f  # v4.8.0
         with:
           git-config-name: cuda-python-bot
           git-config-email: cuda-python-bot@users.noreply.github.com
+          branch: ${{ inputs.docs-branch }}
           folder: artifacts/docs/
           target-folder: docs/
           commit-message: "Deploy ${{ (inputs.is-release && 'release') || 'latest' }} docs: ${{ env.CUDA_PYTHON_DOCS_GITHUB_REF }}"

.github/workflows/release-upload.yml

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: Copyright (c) 2024-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-FileCopyrightText: Copyright (c) 2024-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 #
 # SPDX-License-Identifier: Apache-2.0
 
@@ -18,6 +18,11 @@ on:
         description: "Component to download wheels for"
         type: string
         required: true
+      dry-run:
+        description: "Validate release artifacts without uploading them to the GitHub release"
+        type: boolean
+        required: false
+        default: false
 
 concurrency:
   # Concurrency group that uses the workflow name and PR number if available
@@ -64,6 +69,7 @@ jobs:
           > "release/${{ env.ARCHIVE_NAME }}.tar.gz.sha256sum"
 
       - name: Upload Archive
+        if: ${{ !inputs.dry-run }}
         env:
           GH_TOKEN: ${{ github.token }}
         run: >
@@ -72,7 +78,7 @@ jobs:
           --repo "${{ github.repository }}"
           release/*
 
-      - name: Download and Upload Wheels
+      - name: Download and Validate Wheels
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
@@ -82,8 +88,20 @@ jobs:
           # Validate that release wheels match the expected version from tag.
           ./ci/tools/validate-release-wheels "${{ inputs.git-tag }}" "${{ inputs.component }}" "release/wheels"
 
-          # Upload wheels to the release
+      - name: Upload Wheels
+        if: ${{ !inputs.dry-run }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
           if [[ -d "release/wheels" && $(ls -A release/wheels 2>/dev/null | wc -l) -gt 0 ]]; then
             echo "Uploading wheels to release ${{ inputs.git-tag }}"
             gh release upload --clobber "${{ inputs.git-tag }}" --repo "${{ github.repository }}" release/wheels/*
           fi
+
+      - name: Upload dry-run release artifacts
+        if: ${{ inputs.dry-run }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: release-artifacts-dry-run-${{ inputs.component }}-${{ inputs.git-tag }}
+          path: release/
+          retention-days: 3

.github/workflows/release.yml

@@ -1,12 +1,34 @@
-# SPDX-FileCopyrightText: Copyright (c) 2024-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-FileCopyrightText: Copyright (c) 2024-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 #
 # SPDX-License-Identifier: Apache-2.0
 
 name: "CI: Release"
 
 # Manually-triggered release workflow. Creates a release draft if one doesn't exist
 # for the given tag, or uses an existing draft, then publishes the selected wheels
-# to TestPyPI followed by PyPI.
+# to TestPyPI followed by PyPI. The dry-run mode validates the release path
+# without publishing to external release surfaces.
+#
+# Maintenance note: non-trivial changes to this workflow should be validated
+# with dry-run workflow_dispatch runs before merging. Suggested focused matrix:
+# - mainline:
+#   component=cuda-bindings
+#   git-tag=<latest cuda-bindings release tag>
+#   backport-git-tag=not planned
+#   run-id=<blank>
+#   dry-run-docs-branch=gh-pages-dry-run
+# - backport sequence:
+#   1. component=cuda-bindings
+#      git-tag=<latest cuda-bindings backport release tag>
+#      backport-git-tag=<blank>
+#   2. component=cuda-python
+#      git-tag=<matching cuda-python backport release tag>
+#      backport-git-tag=<blank>
+#   run-id=<blank>
+#   dry-run-docs-branch=gh-pages-dry-run
+# Leave run-id blank so determine-run-id is exercised. For exhaustive coverage,
+# add a mainline cuda-python dry-run when changes could affect metapackage
+# artifact validation, docs routing, or component-specific release behavior.
 
 on:
   workflow_dispatch:
@@ -20,15 +42,33 @@ on:
           - cuda-bindings
           - cuda-pathfinder
           - cuda-python
+      release-action:
+        description: "What to run"
+        required: true
+        type: choice
+        options:
+          - dry-run
+          - full-release
+        default: dry-run
       git-tag:
         description: "The release git tag"
         required: true
         type: string
+      backport-git-tag:
+        description: "Mainline cuda-bindings/cuda-python only: planned backport tag, or 'not planned'. Leave blank for backport releases."
+        required: false
+        type: string
+        default: ""
       run-id:
         description: "The GHA run ID that generated validated artifacts (optional - auto-detects successful tag-triggered CI run for git-tag)"
         required: false
         type: string
         default: ""
+      dry-run-docs-branch:
+        description: "Dry-run only: optional gh-pages-* branch to receive generated docs, for example gh-pages-dry-run"
+        required: false
+        type: string
+        default: ""
 
 defaults:
   run:
@@ -52,9 +92,14 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
-          echo "Auto-detecting successful tag-triggered run ID for tag: ${{ inputs.git-tag }}"
-          RUN_ID=$(./ci/tools/lookup-run-id "${{ inputs.git-tag }}" "${{ github.repository }}")
-          echo "Auto-detected run ID: $RUN_ID"
+          if [[ -n "${{ inputs.run-id }}" ]]; then
+            echo "Using provided run ID: ${{ inputs.run-id }}"
+            RUN_ID="${{ inputs.run-id }}"
+          else
+            echo "Auto-detecting successful tag-triggered run ID for tag: ${{ inputs.git-tag }}"
+            RUN_ID=$(./ci/tools/lookup-run-id "${{ inputs.git-tag }}" "${{ github.repository }}")
+            echo "Auto-detected run ID: $RUN_ID"
+          fi
           echo "run-id=$RUN_ID" >> "$GITHUB_OUTPUT"
 
   check-tag:
@@ -63,12 +108,31 @@ jobs:
       - name: Checkout Source
         uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
         with:
+          # Dry-run validation resolves the requested tag locally; we need tags but not history.
           fetch-depth: 1
+          fetch-tags: true
 
-      - name: Check or create draft release for the tag
+      - name: Check release tag and draft state
         env:
           GH_TOKEN: ${{ github.token }}
+          RELEASE_ACTION: ${{ inputs.release-action }}
+          RELEASE_GIT_TAG: ${{ inputs.git-tag }}
+          DRY_RUN_DOCS_BRANCH: ${{ inputs.dry-run-docs-branch }}
         run: |
+          if [[ "$RELEASE_ACTION" == "full-release" && -n "$DRY_RUN_DOCS_BRANCH" ]]; then
+            echo "error: dry-run-docs-branch is only valid with release-action=dry-run" >&2
+            exit 1
+          fi
+          if [[ "$RELEASE_ACTION" == "dry-run" && -n "$DRY_RUN_DOCS_BRANCH" && ! "$DRY_RUN_DOCS_BRANCH" =~ ^gh-pages-[[:alnum:]._/-]+$ ]]; then
+            echo "error: dry-run-docs-branch must be a non-production gh-pages-* branch" >&2
+            exit 1
+          fi
+          if [[ "$RELEASE_ACTION" == "dry-run" ]]; then
+            git rev-parse --verify "${RELEASE_GIT_TAG}^{commit}"
+            echo "Dry-run selected; not checking or creating a GitHub release draft."
+            exit 0
+          fi
+
           mapfile -t tags < <(gh release list -R "${{ github.repository }}" --json tagName --jq '.[] | .tagName')
           mapfile -t is_draft < <(gh release list -R "${{ github.repository }}" --json isDraft --jq '.[] | .isDraft')
 
@@ -94,8 +158,6 @@ jobs:
     steps:
       - name: Checkout Source
         uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
-        with:
-          ref: ${{ inputs.git-tag }}
 
       - name: Set up Python
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
@@ -111,7 +173,8 @@ jobs:
         run: |
           python ci/tools/check_release_notes.py \
             --git-tag "${{ inputs.git-tag }}" \
-            --component "${{ inputs.component }}"
+            --component "${{ inputs.component }}" \
+            --backport-git-tag "${{ inputs.backport-git-tag }}"
 
   doc:
     name: Build release docs
@@ -132,9 +195,11 @@ jobs:
       git-tag: ${{ inputs.git-tag }}
       run-id: ${{ needs.determine-run-id.outputs.run-id }}
       is-release: true
+      deploy-docs: ${{ inputs.release-action == 'full-release' || inputs.dry-run-docs-branch != '' }}
+      docs-branch: ${{ (inputs.release-action == 'dry-run' && inputs.dry-run-docs-branch) || 'gh-pages' }}
 
   upload-archive:
-    name: Upload source archive
+    name: Validate release artifacts
     permissions:
       contents: write
     needs:
@@ -148,9 +213,11 @@ jobs:
       git-tag: ${{ inputs.git-tag }}
       run-id: ${{ needs.determine-run-id.outputs.run-id }}
       component: ${{ inputs.component }}
+      dry-run: ${{ inputs.release-action == 'dry-run' }}
 
   publish-testpypi:
     name: Publish wheels to TestPyPI
+    if: ${{ inputs.release-action == 'full-release' }}
     runs-on: ubuntu-latest
     needs:
       - check-tag
@@ -183,6 +250,7 @@ jobs:
 
   publish-pypi:
     name: Publish wheels to PyPI
+    if: ${{ inputs.release-action == 'full-release' }}
     runs-on: ubuntu-latest
     needs:
       - determine-run-id