Add CPU-only fork CI mirror for pre-commit checks

.github/workflows/fork-ci-mirror-fast.yml

@@ -0,0 +1,98 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: BSD-2-Clause
+
+# Fork-internal CI mirror: CPU-only checks for faster feedback
+# This workflow mirrors the upstream's pre-commit and documentation build checks.
+# GPU/CUDA-dependent tests remain an acknowledged gap and are not included.
+# See CI_MIRROR_GAPS.md for details.
+
+name: Fork CI Mirror (CPU-only)
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+  workflow_dispatch:
+  issue_comment:
+    types: [created]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}-${{ github.event_name }}
+  cancel-in-progress: true
+
+jobs:
+  trigger-check:
+    # Only proceed if this is a PR and (event is PR or comment on PR contains /run-ci-mirror)
+    runs-on: ubuntu-latest
+    outputs:
+      should-run: ${{ steps.decide.outputs.should-run }}
+    steps:
+      - name: Decide whether to run
+        id: decide
+        run: |
+          should_run="false"
+          if ${{ github.event_name == 'pull_request' }}; then
+            should_run="true"
+          elif ${{ github.event_name == 'workflow_dispatch' }}; then
+            should_run="true"
+          elif ${{ github.event_name == 'issue_comment' && github.event.issue.pull_request != null }}; then
+            if [[ "${{ github.event.comment.body }}" == *"/run-ci-mirror"* ]]; then
+              should_run="true"
+            fi
+          fi
+          echo "should-run=${should_run}" >> $GITHUB_OUTPUT
+
+  pre-commit:
+    needs: trigger-check
+    if: ${{ needs.trigger-check.outputs.should-run == 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548
+      - uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd
+        with:
+          extra_args: --all-files --show-diff-on-failure
+
+  build-docs:
+    needs: trigger-check
+    if: ${{ needs.trigger-check.outputs.should-run == 'true' }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup pixi
+        uses: prefix-dev/setup-pixi@fef5c9568ca6c4ff7707bf840ab0692ba3f08293
+        with:
+          pixi-version: "v0.61.0"
+          environments: docs
+          cache: false
+      - name: Docs build
+        run: pixi run -e docs build-docs
+        env:
+          GH_TOKEN: ${{ github.token }}
+      - name: Upload docs
+        if: "!cancelled()"
+        uses: actions/upload-artifact@v5
+        with:
+          name: docs
+          path: ${{ github.workspace }}/docs/build/html
+
+  checks:
+    name: Mirror CI Status
+    if: always()
+    runs-on: ubuntu-latest
+    needs:
+      - pre-commit
+      - build-docs
+    steps:
+      - name: Check mirror job status
+        run: |
+          if ${{ needs.pre-commit.result == 'failure' || needs.build-docs.result == 'failure' }}; then
+            echo "One or more mirror CI checks failed."
+            exit 1
+          elif ${{ needs.pre-commit.result == 'cancelled' || needs.build-docs.result == 'cancelled' }}; then
+            echo "One or more mirror CI checks were cancelled."
+            exit 1
+          else
+            echo "All mirror CI checks passed."
+            exit 0
+          fi

CI_MIRROR_GAPS.md

@@ -0,0 +1,68 @@
+# Fork CI Mirror: Coverage and Gaps
+
+This document describes what the fork's CPU-only CI mirror includes and intentionally excludes.
+
+## Mirrored Checks
+
+The fork CI mirror (`fork-ci-mirror-fast.yml`) includes the following CPU-feasible checks:
+
+### 1. Pre-commit Checks
+- Standard pre-commit hooks (check-added-large-files, check-ast, check-merge-conflict, check-toml, check-yaml, debug-statements, end-of-file-fixer, trailing-whitespace, mixed-line-ending)
+- Ruff linting and formatting (ruff, ruff-format)
+- SPDX header validation (check-spdx)
+- Sphinx documentation linting (sphinx-lint)
+
+These checks are language-agnostic, platform-independent, and provide immediate feedback on code style, formatting, and documentation quality.
+
+### 2. Documentation Build
+- Full Sphinx documentation build using pixi environments
+- Validates that documentation builds successfully without errors or warnings (in strict mode)
+- Produces HTML artifacts for preview
+
+## Acknowledged Gaps (Not Mirrored)
+
+The following checks require CUDA runtime or specialized hardware and are **intentionally not mirrored** on the fork:
+
+### 1. Build Workflows
+- Build wheels for linux-64, linux-aarch64, win-64 (require CUDA SDK, platform-specific build tools)
+- Conda package builds (require CUDA toolchain)
+
+### 2. Functional Tests
+- Test wheel (linux, windows)
+- Conda tests (test-conda)
+- Simulator tests (test-simulator)
+- Third-party integration tests (cuDF, nvmath, awkward)
+- Coverage reports
+
+These tests require:
+- CUDA 12.x or 13.x runtime
+- GPU compute capability or CUDA simulator
+- Build artifacts (wheels, conda packages) from upstream
+- Hardware-specific or simulator-based execution
+
+### 3. Why This Gap is Permanent
+
+The fork is configured on `ubuntu-latest` runners, which provide only standard GitHub-hosted Linux infrastructure (no CUDA, no GPU). Full functional testing requires either:
+- Self-hosted NVIDIA GPU runners (not available for this fork)
+- CUDA simulator support (requires additional setup not suitable for general-purpose CI)
+
+The pre-commit and docs-build checks provide fast, actionable feedback on code quality without requiring specialized hardware. For full validation including CUDA functional tests, changes should be tested on an NVIDIA-provided runner or self-hosted GPU infrastructure before upstream submission.
+
+## Triggering the Mirror CI
+
+The mirror CI can be triggered in three ways:
+
+1. **Automatically on PR**: When a PR is opened, synchronized, or reopened
+2. **Manual dispatch**: Using `gh workflow run fork-ci-mirror-fast.yml`
+3. **On-demand via comment**: Comment `/run-ci-mirror` on any existing PR (requires PR edit permissions)
+
+## Success Criteria
+
+A passing fork mirror CI run means:
+- All code follows SPDX header conventions
+- All Python code passes ruff formatting and linting checks
+- All documentation compiles without errors
+- No trailing whitespace or mixed line endings
+- No obvious syntax or merge conflicts
+
+A failing fork mirror CI run indicates code quality issues that should be addressed before upstream submission.