Build native Windows ARM64 gitlab-runner-helper.exe

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).

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), 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), @avonbertoldi and @shanushpt aligned on a 5-MR plan:

  1. MR 1 (done, !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 (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" (by @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) 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) 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 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 by @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). 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 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) 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) — the bundled binary in the existing arm64 helper image stays amd64-via-emulation until MR 3 cuts over.

Related

Edited by Shanush Prema Thasarathan