## Summary Build native Windows ARM64 binaries for `gitlab-runner-helper.exe` (and confirm/finish the equivalent for the main `gitlab-runner.exe`). This is part 2 of the 5-MR plan to deliver full Windows ARM64 support for the docker-windows executor, parent issue [#39182 (closed)](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/39182). This MR is a prerequisite for MR 3, MR 4 and MR 5: without a native arm64 helper binary we cannot drop the amd64-via-emulation workaround shipped in [!6033 (merged)](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6033), we cannot support `nanoserver` on arm64 (nanoserver does not support amd64 emulation), and we cannot reliably rely on the runner's host architecture detection. ## Background After review of [!6033 (merged)](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6033), [@avonbertoldi](https://gitlab.com/avonbertoldi) and [@shanushpt](https://gitlab.com/shanushpt) [aligned on a 5-MR plan](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/39182#note_3218518204): 1. **MR 1 (done, **[**!6033**](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6033)**)** — Add LTSC2025 and LTSC2025-arm64 helper images for windows. Customers must manually specify the helper image. The arm64 helper image bundles the **amd64** `gitlab-runner-helper.exe`, which runs on ARM64 via Windows emulation. 2. **MR 2 (this issue)** — Create the ability to build the arm64 helper executable and arm64 main binary. 3. **MR 3** — Replace the use of the amd64 helper executable in the windows arm64 helper image with the native arm64 binary made available in MR 2. 4. **MR 4** — Add nanoserver 2025 support for arm64/amd64. Requires native arm64 binaries because [nanoserver does not support amd64 emulation](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6033#note_3195872282) (it is too minimal). 5. **MR 5** — Fix `gitlab-runner.exe` to correctly detect that it is running on arm64 and automatically choose the right arm64 docker image on windows. ## What needs to change ### 1. Build native `windows/arm64` `gitlab-runner-helper.exe` * Add `windows/arm64` to the matrix used by the helper-binary build targets (e.g. `mage helperbin:*` / equivalent), alongside the existing `windows/amd64` targets. ### 2. Confirm scope of the main `gitlab-runner.exe` arm64 build [!6495 "Build gitlab-runner-windows-arm64 executable"](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6495) (by [@brunvonlope](https://gitlab.com/brunvonlope), merged 2026-03-11) already adds a build of the main `gitlab-runner.exe` for `windows/arm64`, motivated by the GIMP project's ARM-sponsored shell-executor runners. Before starting this MR: * Verify that [!6495 (merged)](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6495) actually publishes the artifact in the same locations as the amd64 `gitlab-runner-windows-amd64.exe` (release artifacts, S3, package registry, docs). If gaps remain (for example: no signing, no inclusion in release notes, no pusher entry), close them as part of this MR. * If [!6495 (merged)](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6495) is fully sufficient, narrow this MR's scope to **just the helper executable**. The title can then become "Build native Windows ARM64 `gitlab-runner-helper.exe`". ## Out of scope * Changing which binary is bundled into the helper image — that is **MR 3**. * Pusher entry for `windows-servercore-ltsc2025-arm64` is updated from the `x86_64-binary-arm64-platform-...` placeholder to a native `arm64-...` mapping (or equivalent) * Adding `nanoserver:ltsc2025-arm64` or `nanoserver:ltsc2025-amd64` helper images — that is **MR 4**. * Runtime architecture detection in `gitlab-runner.exe` — that is **MR 5**. Note: it was [observed during !6033 review](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6033#note_3195872298) that the runner currently misreports its host architecture as amd64 even when running on an arm64 host; producing the native arm64 main binary here is a prerequisite for fixing that detection in MR 5. * The `helpers/container/helperimage/windows_info.go` mapping of `V24H2` to a new `baseImage25H2` constant. [Raised in review](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6033#note_3188397004) by [@avonbertoldi](https://gitlab.com/avonbertoldi) and intentionally deferred — this will be part of MR 5. * Adding `.instance-windows-2025-arm64` runner tags, `windows25H2` common job templates, `windows 25H2` test jobs, and `ci/.test-failures.servercore25H2.txt` ([!6033 review checklist](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6033#note_3188397004)). These were deferred pending an arm64 windows runner manager being provisioned. Add them only if that runner becomes available before MR 5. ## CI / artifact-size considerations [!6033 hit a `413 Request Entity Too Large`](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6033#note_3232858185) when uploading combined Windows 2025 helper image artifacts (\~4.85 GB total: 2.5 GB arm64 + 2.1 GB amd64). The fix was to split into separate `prebuilt helper images windows 2025` and `prebuilt helper images windows 2025 arm64` jobs. Any new arm64 build jobs added here must follow the same per-arch split or risk hitting the same artifact-upload limit. Heads-up: each Windows helper image is \~2.5 GB. ## Acceptance criteria * `gitlab-runner-helper.exe` is built for `windows/arm64` and published per the existing per-arch pusher convention. * If [!6495 (merged)](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6495) does not already cover it: native `windows/arm64` `gitlab-runner.exe` is published as a release artifact, signed and named consistently with the existing `gitlab-runner-windows-amd64.exe`. * CI pipeline produces and uploads the new arm64 artifacts on `main`, MRs (per existing rules) and tag builds, without exceeding artifact-size limits. * No behaviour change for existing amd64 builds or for the helper images shipped by [!6033 (merged)](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6033) — the bundled binary in the existing arm64 helper image stays amd64-via-emulation until MR 3 cuts over. ## Related * Parent issue: [#39182 (closed)](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/39182) * Previous MR: [!6033 (merged)](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6033) * Related MR (main binary, already merged): [!6495 (merged)](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6495) * Base-images dependency (provides arm64 windows base images): [gitlab-org/ci-cd/runner-tools/base-images!88 (merged)](https://gitlab.com/gitlab-org/ci-cd/runner-tools/base-images/-/merge_requests/88), [!111](https://gitlab.com/gitlab-org/ci-cd/runner-tools/base-images/-/merge_requests/111)