## 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](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/39182). This is the user-visible performance win of the ARM64 work: customers who already opted into the arm64 helper image via [!6033 (merged)](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6033) start running the helper natively instead of under emulation, with no config change on their side. ## 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. The arm64 image bundles the **amd64** helper binary, running under Windows emulation as a deliberate, documented workaround. 2. **MR 2** (#39416) — 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](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6033#note_3195872282). 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`](https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/dockerfiles/runner-helper/docker-bake.hcl) currently contains, courtesy of [!6033 (merged)](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6033): ```dockerfile 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`](https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/scripts/pusher/helper-images.json), the entry added by [!6033 (merged)](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6033) encodes the workaround in the artifact name: ```json "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)](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6033)) 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](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6033#note_3188397004) 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](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/39182) * Depends on: MR 2 (native arm64 `gitlab-runner-helper.exe`) * Previous MR: [!6033 (merged)](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6033) * Followed by: MR 4 (nanoserver 2025 arm64/amd64), MR 5 (host arch detection + auto-selection)