Bundle the native ARM64 gitlab-runner-helper.exe in the Windows ARM64 helper image

Summary

Switch the Windows ARM64 helper image (windows-servercore-ltsc2025-arm64) from bundling the amd64 gitlab-runner-helper.exe (running via Windows emulation) to bundling the native arm64 gitlab-runner-helper.exe produced in MR 2. This is part 3 of the 5-MR plan to deliver full Windows ARM64 support for the docker-windows executor, parent issue #39182 (closed).

This is the user-visible performance win of the ARM64 work: customers who already opted into the arm64 helper image via !6033 (merged) start running the helper natively instead of under emulation, with no config change on their side.

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. The arm64 image bundles the amd64 helper binary, running under Windows emulation as a deliberate, documented workaround.
  2. MR 2 (#39416 (closed)) — Build the native arm64 gitlab-runner-helper.exe (and confirm/finalise arm64 gitlab-runner.exe).
  3. MR 3 (this issue) — Replace the amd64-via-emulation helper binary in the arm64 helper image with the native arm64 binary produced by MR 2.
  4. MR 4 — Add nanoserver 2025 support for arm64/amd64. Depends on MR 3 because nanoserver does not support amd64 emulation.
  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. Remove the TARGETARCH override in docker-bake.hcl

dockerfiles/runner-helper/docker-bake.hcl currently contains, courtesy of !6033 (merged):

TARGETARCH = "amd64"  # Force override of TARGETARCH because arm64 runner-helper is not yet # available; amd64 version of runner-helper works on arm64 Windows via emulation.

This override makes every windows target (including the arm64 matrix entry) pull the amd64 binary into the resulting image. Once MR 2 is merged, this line must be removed so each matrix entry resolves TARGETARCH from item.arch (i.e. amd64 or arm64) like the rest of the bake file expects.

2. Update the pusher mapping

In scripts/pusher/helper-images.json, the entry added by !6033 (merged) encodes the workaround in the artifact name:

"windows-servercore-ltsc2025-arm64": [
  "x86_64-binary-arm64-platform-%-servercore24H2" 
]

Update this to a native naming consistent with the rest of the file (e.g. arm64-%-servercore24H2, mirroring how alpine3.21-arm64, ubuntu-arm64, concrete-arm64 are mapped). Coordinate the exact name with whatever MR 2 publishes.

3. Verify the resulting image

  • Build windows-servercore-ltsc2025-arm64 locally (or via the existing prebuilt helper images windows 2025 arm64 CI job) and inspect the image to confirm the bundled gitlab-runner-helper.exe is a PE32+ ARM64 binary, not amd64.
  • Run the helper end-to-end on a Windows ARM64 host (per the test recipe from !6033 (merged)) and confirm a job completes without the emulation overhead.

4. [Out of scope] Documentation / changelog

  • Note in the changelog that the windows-servercore-ltsc2025-arm64 helper image now ships a native arm64 helper binary. Existing customers on this image will pick up the change transparently and should see lower CPU and faster job startup.
  • This change is not a breaking change in API terms, but it does change the binary architecture inside an existing image tag — call that out explicitly so customers running unusual host setups (e.g. odd kernel/Hyper-V configurations) know what changed.
  • A separate issue will be created to track this documentation update.

Out of scope

  • Building the native arm64 helper executable — that is MR 2.
  • nanoserver:ltsc2025-arm64 and nanoserver:ltsc2025-amd64 helper images — that is MR 4. Nanoserver becomes possible only because MR 3 lands a native arm64 helper binary, but the actual nanoserver image work is its own MR.
  • Runtime architecture detection in gitlab-runner.exe and automatic selection of the arm64 helper image — that is MR 5. After MR 3, customers still need to manually set helper_image to the arm64 variant (same UX as after MR 1).
  • Changes to helpers/container/helperimage/windows_info.go to add a baseImage25H2 constant. Raised in review and intentionally deferred to MR 5.

Acceptance criteria

  • The gitlab-runner-helper.exe shipped inside windows-servercore-ltsc2025-arm64 is a native ARM64 PE binary.
  • TARGETARCH = "amd64" override and its accompanying comment are removed from dockerfiles/runner-helper/docker-bake.hcl.
  • scripts/pusher/helper-images.json entry for windows-servercore-ltsc2025-arm64 no longer references x86_64-binary-arm64-platform-....
  • CI builds and publishes the updated arm64 helper image without exceeding artifact-size limits.
  • A docker-windows job using this image on a Windows ARM64 host completes successfully and no longer pays the amd64-emulation cost.
  • Changelog entry documents that the arm64 helper image now ships a native arm64 binary.

Related

  • Parent issue: #39182 (closed)
  • Depends on: MR 2 (native arm64 gitlab-runner-helper.exe)
  • Previous MR: !6033 (merged)
  • Followed by: MR 4 (nanoserver 2025 arm64/amd64), MR 5 (host arch detection + auto-selection)