## Summary Make `gitlab-runner.exe` correctly identify when it is running on a Windows ARM64 host and automatically pick the `arm64` variant of the helper image, instead of requiring customers to manually set `helper_image` in their runner config. This is the final part (5 of 5) of the plan to deliver full Windows ARM64 support for the docker-windows executor, parent issue [#39182](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/39182). After this MR, a customer can install `gitlab-runner.exe` on a Windows ARM64 machine, configure `executor = "docker-windows"`, and have everything work end-to-end with no special configuration — closing out [#39182](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/39182). ## 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 (merged)**](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6033)**)** — Add servercore `ltsc2025` and `ltsc2025-arm64` helper images. Manual `helper_image` config required. 2. **MR 2** (#39416) — Build the native arm64 `gitlab-runner-helper.exe` and finalise arm64 `gitlab-runner.exe` (largely covered by [!6495 (merged)](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6495)). 3. **MR 3** (#39417) — Bundle the native arm64 helper binary in the arm64 servercore image. 4. **MR 4** (#39418) — Add `nanoserver:ltsc2025` and `nanoserver:ltsc2025-arm64` helper images. 5. **MR 5 (this issue)** — Detect Windows ARM64 host and auto-select the right arm64 image. ### Why this MR was deliberately deferred until last There are two reasons the team explicitly punted this work to the end of the plan: 1. **Self-detection is currently broken.** [@shanushpt observed in !6033 review](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6033#note_3195872298): > I think there will be a problem where the gitlab-runner thinks it is on an amd64 even tho it is running on an arm machine. I'm not sure why, it might be because the gitlab-runner executable itself is also an amd64 executable, but I'm not sure if this is the only reason. This probably blocks the ability to do 5 at this moment and would warrant a thorough investigation. A native arm64 `gitlab-runner.exe` (delivered by [!6495 (merged)](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6495) / MR 2) is a prerequisite — `runtime.GOARCH` and similar host-detection signals only return `arm64` when the binary itself is arm64. 2. **`windows_info.go` mapping needs updating.** [@avonbertoldi flagged in !6033 review](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6033#note_3188397004): > `version.go` has `V24H2` (Windows Server 2025 LTSC) but `windows_info.go` maps `V24H2` to reuse the `baseImage21H2` (servercore21H2) helper image. If the intent is that arm64 hosts running Windows Server 2025 should pick up the new ltsc2025-arm64 helper image, this mapping needs a new `baseImage25H2` constant and corresponding `prebuiltImages` entry. Currently the code would serve an amd64 servercore21H2 prebuilt to a V24H2 host, not the new arm64 image. This MR resolves both gaps in one place. ## What needs to change ### 1. Reliable host arch detection In the relevant code path (likely `helpers/container/windows/version.go` and `helpers/container/helperimage/windows_info.go`, plus any caller that builds the helper image reference), determine the host architecture and surface it alongside the existing Windows version. Investigate and confirm the root cause of [@shanushpt's earlier observation](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6033#note_3195872298) that the runner reports amd64 on an arm64 host. Likely candidates to inspect: * The arch is read from a Windows API / WMI / registry lookup that under emulation returns the emulated arch (amd64) instead of the real host arch — common WoW64-style trap. If so, use an API that returns the **native** machine type (e.g. `IsWow64Process2`), not the process-level arch. * The arch is inferred from `runtime.GOARCH`, which reports the binary's arch. With a native arm64 `gitlab-runner.exe` from [!6495 (merged)](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6495), this would now report correctly — but only as long as the runner is the native build. Either way, prefer an OS-level native-arch query so the detection works even if a customer is still running the amd64 binary on arm64 hardware. State the chosen mechanism explicitly in the commit message and document it inline. Add a regression test: an amd64 build running under emulation must still report `arm64` when the host is arm64. ### 2. Add a `baseImage25H2` constant and `prebuiltImages` entry In [`helpers/container/helperimage/windows_info.go`](https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/helpers/container/helperimage/windows_info.go): * Introduce a new `baseImage25H2` constant for Windows Server 2025. * Add a `prebuiltImages` entry mapping `V24H2` (Windows Server 2025 LTSC, defined in [`version.go`](https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/helpers/container/windows/version.go)) to the new constant **and** to the host architecture. * Stop reusing `baseImage21H2` for `V24H2` hosts. ### 3. Architecture-aware helper image selection Extend the helper-image lookup so it returns: * `windows-servercore-ltsc2025-arm64` (or `windows-nanoserver-ltsc2025-arm64`, depending on the `helper_image_flavor` setting) when the host is **Windows Server 2025 + arm64**. * `windows-servercore-ltsc2025` (or `windows-nanoserver-ltsc2025`) when the host is **Windows Server 2025 + amd64**. * The existing 2019 / 2022 mappings unchanged for amd64 hosts on those Windows versions. * A clear, actionable error message if the host is `arm64` on a Windows version Microsoft does not publish arm64 base images for (i.e. Windows Server 2019 / 2022). Refer the user to [#39182](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/39182) for context. Respect any explicit `helper_image` override the user has set in `config.toml` — do not auto-replace it. ### 4. Tests Mirror the existing table-driven tests in `windows_info_test.go`: * Cover `(V24H2, amd64) → servercore-ltsc2025` / `nanoserver-ltsc2025`. * Cover `(V24H2, arm64) → servercore-ltsc2025-arm64` / `nanoserver-ltsc2025-arm64`. * Cover `(V21H2, arm64)` and `(V1809, arm64)` returning a clear error or unsupported-combination signal. * Cover the existing amd64 cases for V1809 / V21H2 — they must continue to behave exactly as before. This is the regression guard against breaking docker-windows on existing customer fleets. ### 5. Documentation * In the runner docs page describing helper-image selection, add a paragraph on automatic Windows ARM64 selection and the supported `(Windows version, host arch)` combinations. * Add a changelog entry: "GitLab Runner now automatically selects the arm64 helper image on Windows ARM64 hosts. Customers who set `helper_image` manually as a workaround during the [#39182](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/39182) rollout can now remove that override." * Close [#39182](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/39182) when this MR merges. ## Out of scope * Building any new helper images — that was MR 1 / MR 4. * Changing the binary inside the existing arm64 helper image — that was MR 3. * Building the arm64 `gitlab-runner.exe` itself — that is MR 2 / [!6495 (merged)](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6495). * Adding `arm64` support for Windows Server 2019 / 2022 helper images — Microsoft does not publish those base images ([@avonbertoldi confirmed in !6033](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6033#note_3204425832)). Detection must produce a clear error in that combination, not silently fall back to amd64-via-emulation. * Making nanoserver the default flavour on Windows. Out of scope; track separately if pursued. ## Risk and mitigations * **Silent regression for existing docker-windows customers.** Auto-selection logic touches the hot path that every docker-windows job goes through. Mitigation: regression test every existing `(version, arch)` combo, gate the new selection branch behind explicit version/arch checks (do not rewrite the whole switch), and follow the [AGENTS.md guidance](https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/AGENTS.md) that "new config fields that change existing behaviour must default to preserving the old behaviour". * **Detection under emulation returns the wrong arch.** Use a native-arch OS API (e.g. `IsWow64Process2`'s `NativeMachine` output), not `runtime.GOARCH`. Add an explicit test that asserts the chosen API returns arm64 when an amd64 binary is running on arm64 hardware. Without this, customers running the older amd64 `gitlab-runner.exe` on arm64 hardware would silently keep getting the amd64 image. * **Customer with explicit `helper_image` override.** Do not overwrite it. Auto-selection is a default, not a force. ## Acceptance criteria * [ ] `gitlab-runner.exe` correctly reports `arm64` when running on a Windows ARM64 host, regardless of whether the binary itself is amd64 (emulated) or arm64 (native). * [ ] A new `baseImage25H2` constant exists in `windows_info.go` with `prebuiltImages` entries for both amd64 and arm64. * [ ] On a Windows Server 2025 ARM64 host, a docker-windows job with no `helper_image` set in `config.toml` automatically uses the arm64 helper image and runs end-to-end successfully. * [ ] On a Windows Server 2025 amd64 host, a docker-windows job with no `helper_image` set automatically uses `windows-servercore-ltsc2025` (or the nanoserver equivalent per `helper_image_flavor`). * [ ] On Windows Server 2019 / 2022 hosts, behaviour is unchanged (regression-tested). * [ ] On a Windows ARM64 host running an unsupported Windows version, the runner produces a clear error message rather than serving an amd64 image. * [ ] Explicit `helper_image` overrides in `config.toml` are respected and not auto-replaced. * [ ] Documentation lists the supported `(Windows version, host arch)` combinations and the auto-selection behaviour. * [ ] Changelog entry references [#39182](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/39182). * [ ] [#39182](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/39182) is closed. ## Related * Parent issue (closes on merge): [#39182](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/39182) * Depends on: MR 2 (native arm64 `gitlab-runner.exe`, [!6495 (merged)](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6495)), MR 3 (native arm64 helper binary in image), MR 4 (nanoserver 2025 arm64/amd64) * Previous MR: [!6033 (merged)](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6033) * Reviewer context: [@avonbertoldi's review checklist](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6033#note_3188397004), [@shanushpt's detection-bug observation](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/6033#note_3195872298)