GitHub Actions Windows ARM64 wheel builder

# 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