wheel.yml

# Copyright (c) 2022-2026, The Isaac Lab Project Developers (https://github.com/isaac-sim/IsaacLab/blob/main/CONTRIBUTORS.md).
# All rights reserved.
#
# SPDX-License-Identifier: BSD-3-Clause

name: Build PIP Wheel

on:
  pull_request:
    types: [opened, synchronize, reopened]
  push:
    branches:
      - main
      - develop
      - 'release/**'

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

permissions:
  contents: read
  pull-requests: read

jobs:
  build-wheel:
    name: Build Wheel
    runs-on: ubuntu-latest
    timeout-minutes: 20

    steps:
      - name: Detect wheel-relevant changes
        id: changes
        env:
          GH_TOKEN: ${{ github.token }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
          EVENT_NAME: ${{ github.event_name }}
          REPO: ${{ github.repository }}
        run: |
          set -euo pipefail

          # Keep this workflow unconditionally triggered on PRs so required
          # branch-protection checks are always reported. The build steps below
          # run only when inputs that can affect the wheel have changed.
          patterns=(
            $'^apps/\tStandalone apps packaged in the wheel'
            $'^pyproject\.toml$\tWheel dependency metadata and resolver overrides'
            $'^VERSION$\tPackage version'
            $'^source/\tPython packages'
            $'^tools/wheel_builder/\tWheel build tooling'
            $'^\.github/workflows/wheel\.yml$\tThis workflow file'
          )

          render_table() {
            local files="$1" entry regex desc matched count sample
            echo "| Pattern | What it covers | Matched files |"
            echo "|---|---|---|"
            for entry in "${patterns[@]}"; do
              IFS=$'\t' read -r regex desc <<< "$entry"
              # Feed grep/head from a here-string rather than `printf ... |` so that
              # an early-closing reader (head) cannot SIGPIPE an upstream printf and
              # trip `set -o pipefail` when the file list is large.
              matched=$(grep -E "$regex" <<< "$files" || true)
              if [ -n "$matched" ]; then
                count=$(wc -l <<< "$matched")
                sample=$(head -3 <<< "$matched" | paste -sd ', ' -)
                [ "$count" -gt 3 ] && sample="$sample (and $((count - 3)) more)"
                echo "| \`$regex\` | $desc | $sample |"
              else
                echo "| \`$regex\` | $desc | - |"
              fi
            done
          }

          any_match() {
            local files="$1" entry regex
            for entry in "${patterns[@]}"; do
              IFS=$'\t' read -r regex _ <<< "$entry"
              if grep -qE "$regex" <<< "$files"; then
                return 0
              fi
            done
            return 1
          }

          decide() {
            local decision="$1" reason="$2" files="${3:-}"
            echo "run_build=$decision" >> "$GITHUB_OUTPUT"
            {
              echo "## Wheel build gating"
              echo ""
              if [ "$decision" = "true" ]; then
                echo "The wheel build will **run**: $reason."
              else
                echo "The wheel build will be **skipped**: $reason."
              fi
              if [ -n "$files" ]; then
                echo ""
                render_table "$files"
              fi
            } >> "$GITHUB_STEP_SUMMARY"
          }

          if [ "$EVENT_NAME" != "pull_request" ]; then
            decide true "non-PR event ($EVENT_NAME)"
            exit 0
          fi

          if ! changed_files="$(gh api --paginate "repos/$REPO/pulls/$PR_NUMBER/files" --jq '.[].filename')"; then
            echo "::warning::Could not list changed files; defaulting to building the wheel"
            decide true "fail-safe (could not list changed files)"
            exit 0
          fi

          if any_match "$changed_files"; then
            decide true "wheel-relevant paths changed" "$changed_files"
          else
            decide false "no wheel-relevant paths changed" "$changed_files"
          fi

      - name: Skip wheel build
        if: steps.changes.outputs.run_build == 'false'
        run: echo "Skipping wheel build because this PR does not change wheel inputs."

      - name: Checkout code
        if: steps.changes.outputs.run_build == 'true'
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6
        with:
          fetch-depth: 1
          lfs: true

      - name: Setup Python
        if: steps.changes.outputs.run_build == 'true'
        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
        with:
          python-version: "3.12"
          architecture: x64

      # Compose Docker-image-style metadata for the artifact. The artifact
      # name is what QA sees in `gh run download`, so we make it scannable:
      # isaaclab-<VERSION>-build<RUN_NUMBER>-<SHA7>. The wheel inside follows
      # PEP 440 (VERSION+buildN.SHA7) since pip requires that format.
      - name: Compute wheel metadata
        if: steps.changes.outputs.run_build == 'true'
        id: meta
        run: |
          set -euo pipefail
          version=$(cat VERSION)
          sha_slug="${GITHUB_SHA:0:7}"
          echo "artifact_name=isaaclab-${version}-build${{ github.run_number }}-${sha_slug}" >> "$GITHUB_OUTPUT"

      - name: Build wheel
        if: steps.changes.outputs.run_build == 'true'
        env:
          WHEEL_BUILD_NUMBER: ${{ github.run_number }}
          WHEEL_SHA: ${{ github.sha }}
        run: bash tools/wheel_builder/build.sh

      - name: Upload wheel artifact
        if: steps.changes.outputs.run_build == 'true'
        uses: actions/upload-artifact@v7
        with:
          name: ${{ steps.meta.outputs.artifact_name }}
          path: tools/wheel_builder/build/dist/isaaclab-*.whl
          if-no-files-found: error
          retention-days: 30

      - name: Download wheel artifact for install test
        if: steps.changes.outputs.run_build == 'true'
        uses: actions/download-artifact@v7
        with:
          name: ${{ steps.meta.outputs.artifact_name }}
          path: /tmp/isaaclab-wheel-artifact

      - name: Test wheel extras resolution
        if: steps.changes.outputs.run_build == 'true'
        run: |
          set -euo pipefail

          python -m pip install --user uv
          export PATH="$HOME/.local/bin:$PATH"

          overrides="$GITHUB_WORKSPACE/tools/wheel_builder/uv-overrides.txt"

          cd /tmp

          uv venv --python 3.12 /tmp/isaaclab-wheel-install
          source /tmp/isaaclab-wheel-install/bin/activate
          uv pip install --upgrade pip

          wheel="$(find /tmp/isaaclab-wheel-artifact -name 'isaaclab-*.whl' -print -quit)"
          if [ -z "$wheel" ]; then
            echo "No isaaclab wheel found in downloaded artifact" >&2
            exit 1
          fi

          uv pip install \
            --dry-run \
            --overrides "$overrides" \
            --extra-index-url https://pypi.nvidia.com \
            --index-strategy unsafe-best-match \
            --prerelease=allow \
            "${wheel}[isaacsim,all]"