diff --git a/.github/actionlint.yaml b/.github/actionlint.yaml
index bad051f4642..a76439cbc3d 100644
--- a/.github/actionlint.yaml
+++ b/.github/actionlint.yaml
@@ -12,6 +12,12 @@ self-hosted-runner:
# GitHub supports queued concurrency runs, but the latest actionlint release
# does not yet recognize the concurrency.queue key.
paths:
+ ".github/workflows/build-docs.yml":
+ ignore:
+ - 'unexpected key "queue" for "concurrency" section'
+ ".github/workflows/cleanup-pr-previews.yml":
+ ignore:
+ - 'unexpected key "queue" for "concurrency" section'
".github/workflows/ci-workflow-health.yml":
ignore:
- 'unexpected key "queue" for "concurrency" section'
diff --git a/.github/actions/doc_preview/action.yml b/.github/actions/doc_preview/action.yml
index 0c60b899fbf..c6d049fc792 100644
--- a/.github/actions/doc_preview/action.yml
+++ b/.github/actions/doc_preview/action.yml
@@ -1,9 +1,9 @@
-# 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: Docs in PRs
-description: Preview or clean up docs built from PRs
+description: Preview docs built from PRs
# A re-implementation based on the logic of https://github.com/rossjrw/pr-preview-action/blob/41a957c44a456a34718e9bcf825363194db5e6d5/README.md, due to limitations illustrated in NVIDIA/cuda-python#380.
@@ -18,8 +18,6 @@ inputs:
runs:
using: composite
steps:
- # The steps below are executed only when testing in a PR.
- # Note: the PR previews will be removed once merged to main or release/* (see below)
- name: Deploy doc preview
if: ${{ github.ref_name != 'main' && !startsWith(github.ref_name, 'release/') }}
uses: JamesIves/github-pages-deploy-action@d92aa235d04922e8f08b40ce78cc5442fcfbfa2f # v4.8.0
@@ -29,6 +27,11 @@ runs:
folder: ${{ inputs.source-folder }}
target-folder: docs/pr-preview/pr-${{ inputs.pr-number }}/
commit-message: "Deploy doc preview for PR ${{ inputs.pr-number }} (${{ github.sha }})"
+ # Every PR preview, the main docs deploy, and the coverage deploy commit to
+ # the shared gh-pages branch. Rebase onto a deployment that landed in the
+ # meantime instead of force-pushing over it, which the branch ruleset
+ # rejects (and which used to discard the other deployment).
+ force: false
- name: Leave a comment after deployment
if: ${{ github.ref_name != 'main' && !startsWith(github.ref_name, 'release/') }}
@@ -45,27 +48,3 @@ runs:
|
https://nvidia.github.io/cuda-python/pr-preview/pr-${{ inputs.pr-number }}/cuda-bindings/
|
https://nvidia.github.io/cuda-python/pr-preview/pr-${{ inputs.pr-number }}/cuda-pathfinder/
|
Preview will be ready when the GitHub Pages deployment is complete.
-
- # The steps below are executed only when building on main or release/*.
- - name: Remove doc preview
- if: ${{ github.ref_name == 'main' || startsWith(github.ref_name, '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
- folder: ${{ inputs.source-folder }}
- target-folder: docs/pr-preview/pr-${{ inputs.pr-number }}/
- commit-message: "Clean up doc preview for PR ${{ inputs.pr-number }} (${{ github.sha }})"
-
- - name: Leave a comment after removal
- if: ${{ github.ref_name == 'main' || startsWith(github.ref_name, 'release/') }}
- uses: marocchino/sticky-pull-request-comment@d4d6b0936434b21bc8345ad45a440c5f7d2c40ff # v3.0.3
- with:
- header: pr-preview
- number: ${{ inputs.pr-number }}
- hide_and_recreate: true
- hide_classify: "OUTDATED"
- message: |
- Doc Preview CI
- :---:
- Preview removed because the pull request was closed or merged.
diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml
index bef2a7e84c0..e3c4409e4ca 100644
--- a/.github/workflows/build-docs.yml
+++ b/.github/workflows/build-docs.yml
@@ -50,6 +50,10 @@ jobs:
# The build stage could fail but we want the CI to keep moving.
if: ${{ github.repository_owner == 'nvidia' && !cancelled() }}
runs-on: ubuntu-latest
+ outputs:
+ deployment-artifact-name: ${{ steps.deployment-metadata.outputs.deployment-artifact-name }}
+ docs-github-ref: ${{ steps.deployment-metadata.outputs.docs-github-ref }}
+ pr-number: ${{ steps.deployment-metadata.outputs.pr-number }}
defaults:
run:
shell: bash -el {0}
@@ -221,11 +225,15 @@ jobs:
if: ${{ !inputs.is-release }}
uses: ./.github/actions/get_pr_number
- - name: Set up artifact directories
+ - name: Record deployment metadata
+ id: deployment-metadata
run: |
- mkdir -p artifacts/docs
- # create an empty folder for removal use
- mkdir -p artifacts/empty_docs
+ echo "deployment-artifact-name=docs-deployment-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}" >> "$GITHUB_OUTPUT"
+ echo "docs-github-ref=${CUDA_PYTHON_DOCS_GITHUB_REF}" >> "$GITHUB_OUTPUT"
+ echo "pr-number=${PR_NUMBER:-}" >> "$GITHUB_OUTPUT"
+
+ - name: Set up artifact directories
+ run: mkdir -p artifacts/docs
- name: Build all docs
if: ${{ inputs.component == 'all' }}
@@ -330,6 +338,16 @@ jobs:
path: artifacts/
retention-days: 3
+ - name: Upload docs deployment payload
+ if: ${{ inputs.deploy-docs }}
+ uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+ with:
+ name: ${{ steps.deployment-metadata.outputs.deployment-artifact-name }}
+ path: artifacts/docs/
+ retention-days: 3
+ include-hidden-files: true
+ if-no-files-found: error
+
- 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
@@ -338,16 +356,43 @@ jobs:
path: artifacts/docs/
retention-days: 3
- - name: Deploy or clean up doc preview
- if: ${{ inputs.deploy-docs && !inputs.is-release }}
+ deploy:
+ name: Deploy docs
+ # GitHub discards prerequisite artifacts on a new run attempt. If only this
+ # job fails, use "Re-run all jobs" so the build recreates its payload.
+ needs: build
+ if: ${{ inputs.deploy-docs && needs.build.result == 'success' }}
+ runs-on: ubuntu-latest
+ # Must match every job that writes to gh-pages.
+ concurrency:
+ group: cuda-python-gh-pages-publish
+ queue: max
+ cancel-in-progress: false
+ defaults:
+ run:
+ shell: bash -el {0}
+ steps:
+ - name: Checkout ${{ github.event.repository.name }}
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ with:
+ fetch-depth: 1
+ ref: ${{ inputs.git-tag }}
+
+ - name: Download docs deployment payload
+ uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+ with:
+ name: ${{ needs.build.outputs.deployment-artifact-name }}
+ path: artifacts/docs/
+
+ - name: Deploy doc preview
+ if: ${{ !inputs.is-release && github.ref_name != 'main' && !startsWith(github.ref_name, 'release/') }}
uses: ./.github/actions/doc_preview
with:
- source-folder: ${{ (github.ref_name != 'main' && 'artifacts/docs') ||
- 'artifacts/empty_docs' }}
- pr-number: ${{ env.PR_NUMBER }}
+ source-folder: artifacts/docs
+ pr-number: ${{ needs.build.outputs.pr-number }}
- name: Deploy doc update
- if: ${{ inputs.deploy-docs && (github.ref_name == 'main' || inputs.is-release) }}
+ if: ${{ github.ref_name == 'main' || inputs.is-release }}
uses: JamesIves/github-pages-deploy-action@fa24774553152dd7873cd16ebd8d959b010c5445 # v4.9.0
with:
git-config-name: cuda-python-bot
@@ -355,5 +400,8 @@ jobs:
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 }}"
+ commit-message: "Deploy ${{ (inputs.is-release && 'release') || 'latest' }} docs: ${{ needs.build.outputs.docs-github-ref }}"
clean: false
+ # Rebase onto concurrent PR-preview or coverage deployments instead of
+ # force-pushing, which the gh-pages ruleset rejects.
+ force: false
diff --git a/.github/workflows/cleanup-pr-previews.yml b/.github/workflows/cleanup-pr-previews.yml
index 4c367f415c3..d411507e004 100644
--- a/.github/workflows/cleanup-pr-previews.yml
+++ b/.github/workflows/cleanup-pr-previews.yml
@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
#
# SPDX-License-Identifier: Apache-2.0
@@ -9,13 +9,6 @@ on:
# Run every night at 11pm EST (4am UTC during EST, 3am UTC during EDT)
# Using 4am UTC to be safe during EST (Nov-Mar)
- cron: '0 4 * * *'
- workflow_dispatch:
- inputs:
- dry-run:
- description: 'Run in dry-run mode (preview only, no changes)'
- required: false
- default: false
- type: boolean
permissions:
contents: write # Required to push changes to gh-pages branch
@@ -24,6 +17,11 @@ jobs:
cleanup:
name: Clean up stale PR preview folders
runs-on: ubuntu-latest
+ # Must match every job that writes to gh-pages.
+ concurrency:
+ group: cuda-python-gh-pages-publish
+ queue: max
+ cancel-in-progress: false
# Only run for NVIDIA org to prevent forks from running this
if: github.repository_owner == 'NVIDIA'
steps:
@@ -41,28 +39,21 @@ jobs:
git config --global user.email "cuda-python-bot@users.noreply.github.com"
- name: Run PR preview cleanup script
+ id: cleanup
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- run: |
- # Determine if we should run in dry-run mode
- if [[ "${{ inputs.dry-run }}" == "true" ]]; then
- echo "Running in dry-run mode (preview only)"
- ./ci/cleanup-pr-previews --dry-run
- else
- echo "Running cleanup with push to gh-pages"
- ./ci/cleanup-pr-previews --push
- fi
+ GH_PAGES_PUBLISH_LOCK: cuda-python-gh-pages-publish
+ run: ./ci/cleanup-pr-previews --push
- name: Summary
if: always()
run: |
echo "### PR Preview Cleanup Summary" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
- if [[ "${{ inputs.dry-run }}" == "true" ]]; then
- echo "✅ Dry-run completed successfully" >> $GITHUB_STEP_SUMMARY
- echo "No changes were made to the gh-pages branch" >> $GITHUB_STEP_SUMMARY
+ if [[ "${{ steps.cleanup.outcome }}" != "success" ]]; then
+ echo "❌ Cleanup failed; no successful update was confirmed" >> $GITHUB_STEP_SUMMARY
else
- echo "✅ Cleanup completed and changes pushed to gh-pages" >> $GITHUB_STEP_SUMMARY
+ echo "✅ Cleanup completed; gh-pages is up to date" >> $GITHUB_STEP_SUMMARY
fi
echo "" >> $GITHUB_STEP_SUMMARY
echo "Workflow run: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}" >> $GITHUB_STEP_SUMMARY
diff --git a/.github/workflows/coverage.yml b/.github/workflows/coverage.yml
index 6015db55c9d..2f66aa4e156 100644
--- a/.github/workflows/coverage.yml
+++ b/.github/workflows/coverage.yml
@@ -465,7 +465,7 @@ jobs:
if-no-files-found: error
combine-and-deploy:
- name: Combine Coverage and Deploy
+ name: Combine Coverage
needs: [coverage-linux, coverage-windows]
runs-on: ubuntu-latest
if: ${{ always() && github.repository_owner == 'nvidia' }}
@@ -566,6 +566,30 @@ jobs:
retention-days: 7
include-hidden-files: true
+ deploy:
+ name: Deploy Coverage
+ # GitHub discards prerequisite artifacts on a new run attempt. If only this
+ # job fails, use "Re-run all jobs" so coverage recreates its payload.
+ needs: combine-and-deploy
+ if: ${{ needs.combine-and-deploy.result == 'success' && github.repository_owner == 'nvidia' }}
+ runs-on: ubuntu-latest
+ permissions:
+ contents: write
+ # Must match every job that writes to gh-pages.
+ concurrency:
+ group: cuda-python-gh-pages-publish
+ queue: max
+ cancel-in-progress: false
+ steps:
+ - name: Checkout ${{ github.event.repository.name }}
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+ - name: Download combined coverage results
+ uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+ with:
+ name: coverage-combined
+ path: docs/coverage/
+
- name: Deploy to gh-pages
uses: JamesIves/github-pages-deploy-action@fa24774553152dd7873cd16ebd8d959b010c5445 # v4.9.0
with:
@@ -575,3 +599,6 @@ jobs:
target-folder: docs/
commit-message: "Deploy combined coverage (Linux + Windows): ${{ github.sha }}"
clean: false
+ # Rebase onto concurrent docs deployments instead of force-pushing,
+ # which the gh-pages ruleset rejects.
+ force: false
diff --git a/ci/cleanup-pr-previews b/ci/cleanup-pr-previews
index 17fd89ab6c0..431289efc6d 100755
--- a/ci/cleanup-pr-previews
+++ b/ci/cleanup-pr-previews
@@ -1,6 +1,6 @@
#!/usr/bin/env bash
-# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
#
# SPDX-License-Identifier: Apache-2.0
@@ -29,14 +29,13 @@ USAGE: $0 [OPTIONS]
OPTIONS:
-n, --dry-run Preview what would be deleted without actually deleting
- --push Commit and push changes to gh-pages (default: false, requires manual push)
+ --push Commit and push from the scheduled GitHub Actions workflow
-h, --help Show this help message
EXAMPLES:
$0 -n # Preview what would be cleaned up (RECOMMENDED FIRST)
- $0 # Clean up folders locally (no push)
- $0 --push # Clean up folders and push to gh-pages branch
- $0 --dry-run --push # Invalid combination (dry-run takes precedence)
+ $0 # Clean up folders locally for inspection (no push)
+ $0 --dry-run --push # Dry run; --push is ignored
REQUIREMENTS:
- GH_TOKEN environment variable must be set with appropriate permissions
@@ -45,8 +44,10 @@ REQUIREMENTS:
SAFETY:
Always run with --dry-run first to verify expected behavior before actual cleanup.
-The script will show a summary of what would be removed. Use --push to automatically
-commit and push changes, otherwise manual git operations are required.
+Without --push, changes are committed locally for inspection only.
+
+Remote updates are owned by the nightly "Cleanup: PR Preview Documentation"
+workflow so they share its deployment lock. Other push contexts are rejected.
This script is specifically designed for the NVIDIA/cuda-python repository structure.
EOF
@@ -80,6 +81,16 @@ while [[ $# -gt 0 ]]; do
esac
done
+# Remote cleanup is restricted to the nightly job so all preview deletions have
+# one owner and participate in the shared gh-pages concurrency queue.
+if [[ "$PUSH_CHANGES" == "true" && "$DRY_RUN" != "true" ]] &&
+ [[ "${GITHUB_ACTIONS:-}" != "true" ||
+ "${GITHUB_EVENT_NAME:-}" != "schedule" ||
+ "${GH_PAGES_PUBLISH_LOCK:-}" != "cuda-python-gh-pages-publish" ]]; then
+ echo -e "${RED}[ERROR]${NC} --push is reserved for the scheduled PR preview cleanup workflow" >&2
+ exit 1
+fi
+
# Validate required tools and environment
echo -e "${YELLOW}[INFO]${NC} Checking prerequisites..."
@@ -212,11 +223,12 @@ else
}
trap cleanup_worktree EXIT
- # Ensure the local gh-pages branch is up-to-date
- git fetch origin gh-pages:gh-pages
+ # Track the remote branch without overwriting a user's local gh-pages branch.
+ git fetch origin +refs/heads/gh-pages:refs/remotes/origin/gh-pages
+ GH_PAGES_SHA=$(git rev-parse refs/remotes/origin/gh-pages)
echo -e "${YELLOW}[INFO]${NC} Creating git worktree for gh-pages branch..."
- if ! git worktree add "$TEMP_DIR" gh-pages >/dev/null 2>&1; then
+ if ! git worktree add --detach "$TEMP_DIR" "$GH_PAGES_SHA" >/dev/null 2>&1; then
echo -e "${RED}[ERROR]${NC} Failed to create git worktree for gh-pages branch" >&2
# Check if the issue might be a leftover worktree registration
@@ -226,7 +238,7 @@ else
rm -rf "$TEMP_DIR" >/dev/null 2>&1 || true
# Try again
- if ! git worktree add "$TEMP_DIR" gh-pages >/dev/null 2>&1; then
+ if ! git worktree add --detach "$TEMP_DIR" "$GH_PAGES_SHA" >/dev/null 2>&1; then
echo -e "${RED}[ERROR]${NC} Still unable to create worktree after cleanup" >&2
exit 1
fi
@@ -267,13 +279,26 @@ $(if [[ ${#FOLDERS_TO_REMOVE[@]} -gt 20 ]]; then echo "... and $((${#FOLDERS_TO_
if [[ "$PUSH_CHANGES" == "true" ]]; then
echo -e "${YELLOW}[INFO]${NC} Pushing to gh-pages branch..."
- git push origin gh-pages
- CHANGES_PUSHED="true"
+ CHANGES_PUSHED="false"
+ for attempt in 1 2 3; do
+ if git push origin HEAD:refs/heads/gh-pages; then
+ CHANGES_PUSHED="true"
+ break
+ fi
+ if [[ "$attempt" -eq 3 ]]; then
+ echo -e "${RED}[ERROR]${NC} Push to gh-pages rejected after ${attempt} attempts" >&2
+ exit 1
+ fi
+ echo -e "${YELLOW}[INFO]${NC} gh-pages advanced; rebasing before retry $((attempt + 1))/3..."
+ git fetch origin +refs/heads/gh-pages:refs/remotes/origin/gh-pages
+ git rebase refs/remotes/origin/gh-pages
+ done
echo -e "${GREEN}[SUCCESS]${NC} Cleanup completed! Removed ${REMOVED_COUNT} PR preview folders and pushed changes"
else
CHANGES_PUSHED="false"
echo -e "${GREEN}[SUCCESS]${NC} Cleanup completed! Removed ${REMOVED_COUNT} PR preview folders"
- echo -e "${YELLOW}[INFO]${NC} Changes have been committed locally but not pushed. Use 'git push origin gh-pages' to push manually."
+ echo -e "${YELLOW}[INFO]${NC} Changes have been committed locally for inspection but not pushed."
+ echo -e "${YELLOW}[INFO]${NC} The nightly PR preview cleanup workflow owns remote deletions."
echo -e "${YELLOW}[WARNING]${NC} Worktree will be preserved for manual verification."
fi
else