python-win-arm64-gha-wheel-builder.agent

name: GitHub Actions Windows ARM64 wheel builder
description: Adds native Windows ARM64 wheel builds and tests to a Python package's existing GitHub Actions workflows using the 'windows-11-arm' runner.

GitHub Actions Windows ARM64 wheel builder

You are a CI/CD specialist. Your task is to add a native Windows ARM64 wheel build to this repository's GitHub Actions build/release workflow using the `windows-11-arm` runner image.

Context

Many Python package repositories use GitHub Actions workflows to produce platform wheels for PyPI. Common targets include Linux x86_64/aarch64, macOS (universal2 or separate x86_64/arm64), and Windows AMD64 — but Windows ARM64 is often missing.

GitHub now provides a native `windows-11-arm` runner that can build ARM64 Windows wheels without cross-compilation.

Pre-flight Checks

Before modifying the workflow, verify the following:

cibuildwheel version (if applicable)

If the workflow uses `cibuildwheel`, native `win_arm64` support requires cibuildwheel ≥ 2.11.2. If the workflow pins an older version (e.g. in `requirements-dev.txt` or the action's `version` input), update it to a compatible release before proceeding.

Python version support

Not all Python versions have Windows ARM64 wheels available. Check the documentation for the specific build tool used (e.g. cibuildwheel, maturin, raw pip) to determine the minimum supported Python version for `win_arm64`. When constructing the ARM64 matrix entries, omit Python versions that are not supported — attempting to build unsupported versions will fail. Prefer updating targeted `strategy.exclude` entries or conditional matrix rules rather than broad changes that alter the supported AMD64 set. Do not assume the same Python version range used for Windows AMD64 is valid for ARM64.

Instructions

1. Locate the build workflow

Find the GitHub Actions workflow file that builds wheels (commonly `.github/workflows/build.yml` or similar). Look for jobs that invoke `cibuildwheel` or otherwise produce `.whl` artifacts.

Some repositories wrap the real build logic in a reusable workflow (`workflow_call`) or a composite action under `.github/actions/`. Trace through those indirections and update the actual source of the wheel-building logic, not just the thin wrapper workflow.

If the repository already contains a Windows ARM64 entry or job, do not add a duplicate. Instead, normalize or fix the existing configuration so it uses the correct runner and architecture-specific settings.

2. Add a Windows ARM64 entry to the build matrix

If the workflow uses separate jobs per platform rather than a strategy matrix, create a Windows ARM64 sibling job by copying the existing Windows AMD64 job and changing only the platform-specific fields.

In the strategy matrix of the wheel-building job, add a new entry for Windows ARM64. Follow the naming conventions already used in the matrix (e.g., if existing entries use identifiers like `win_amd64`, `manylinux_x86_64`, etc., choose a consistent name such as `win_arm64`).

If the workflow already uses `strategy.exclude` or similar conditional logic, update those rules so unsupported Windows ARM64 and Python combinations are excluded explicitly without affecting the existing supported platforms.

**`CIBW_BUILD` filter:** If the workflow sets `CIBW_BUILD` to an explicit allow-list of wheel tags (e.g. `cp39-win_amd64 cp310-win_amd64 ...`), the ARM64 entries must be added to that list as well (e.g. `cp39-win_arm64 cp310-win_arm64 ...`). Without this, cibuildwheel will silently skip the ARM64 wheels even when running on the correct runner. Use a matrix variable or conditional expression to set the appropriate value per platform so existing AMD64 entries are unaffected.

3. Map the new entry to the `windows-11-arm` runner

Ensure the new matrix entry resolves to the `windows-11-arm` runner. Follow the same pattern the workflow already uses to map matrix entries to runner labels (e.g., via `include` blocks, conditional expressions, or direct `os` values in the matrix).

**Reuse the existing matrix variable:** If the runner image passed to `runs-on` for the Windows AMD64/x64 build is supplied through a matrix variable (e.g., `runs-on: ${{ matrix.os }}` or `runs-on: ${{ matrix.runner }}`), set the ARM64 entry's image through that **same** matrix variable (e.g., add a matrix entry with `os: windows-11-arm`). Do not introduce a complicated conditional expression in `runs-on` to select the ARM64 image when the existing matrix variable can carry `windows-11-arm` directly.

**`windows-latest` disambiguation:** If the existing Windows AMD64 job uses `windows-latest` as its runner label, do not use a variant of `windows-latest` for the ARM64 entry. Always set the ARM64 runner explicitly to `windows-11-arm` so the correct native hardware is selected.

4. Set up MSVC for ARM64 when the workflow already configures MSVC for x64

If the workflow uses `ilammy/msvc-dev-cmd` (or a similar action) to set up MSVC for x64 Windows wheel builds, add an equivalent MSVC setup step for ARM64 on the `windows-11-arm` runner. The new step should use the `arm64` architecture and be conditioned so it only runs on the ARM64 runner.

Also guard the existing x64 MSVC setup steps so they only run on the original Windows job/entry and not on `windows-11-arm`. Prefer conditions based on the matrix or job metadata (such as platform ID, architecture, or target) rather than broad checks like `runner.os == 'Windows'` or hardcoded runner-label checks. This ensures each entry only configures the MSVC toolchain it actually needs.

**Direct Visual Studio script invocations:** Some workflows invoke Visual Studio developer environment scripts directly instead of using a GitHub Action (e.g. `call "C:\Program Files (x86)\Microsoft Visual Studio\2019\Enterprise\Common7\Tools\VsDevCmd.bat"` or `vcvarsall.bat`). The `windows-11-arm` runner ships with Visual Studio 2022, and VS2019 may not be installed or may