enhance: test on Windows and fix what it found (#1348)

Adds a weekly and on-demand workflow that runs the cross-compiled tests on Windows Server 2025 Core in a [dockur/windows](https://github.com/dockur/windows) QEMU VM, and fixes the Windows bugs it found in host and UNC paths, env handling, shell quoting, post-task scripts, health checks, checkout, action symlinks, step summaries, Git client certificates and docker mode from a Windows host.

Host-mode steps now emit UTF-8, `bash` falls back to Git's bash instead of the WSL launcher, the runner can run as a native Windows service, steps can keep background helpers with `RUNNER_TRACKING_ID`, and Windows arm64 binaries are released.

Fixes: https://gitea.com/gitea/runner/issues/1339
Fixes: https://gitea.com/gitea/runner/issues/637
Fixes: https://gitea.com/gitea/runner/issues/1172
Fixes: https://gitea.com/gitea/runner/issues/347
Reviewed-on: https://gitea.com/gitea/runner/pulls/1348
Reviewed-by: bircni <[email protected]>

internal/app/cmd/cmd.go

@@ -46,7 +46,11 @@ func Execute(ctx context.Context) {
 		Use:   "daemon",
 		Short: "Run as a runner daemon",
 		Args:  cobra.MaximumNArgs(0),
-		RunE:  runDaemon(ctx, &daemArgs, &configFile),
+		RunE: func(command *cobra.Command, args []string) error {
+			return runService(ctx, func(ctx context.Context) error {
+				return runDaemon(ctx, &daemArgs, &configFile)(command, args)
+			})
+		},
 	}
 	daemonCmd.Flags().BoolVar(&daemArgs.Once, "once", false, "Run one job then exit")
 	daemonCmd.Flags().StringVar(&daemArgs.Labels, "labels", os.Getenv("GITEA_RUNNER_LABELS"), "Runner labels, comma separated. Overrides the labels of an already registered runner")

internal/app/cmd/config_test.go

@@ -7,6 +7,7 @@ import (
 	"bytes"
 	"os"
 	"path/filepath"
+	"strconv"
 	"testing"
 
 	"gitea.com/gitea/runner/internal/pkg/config"
@@ -38,7 +39,7 @@ func TestConfigCmdInitWritesTheMinimalConfig(t *testing.T) {
 
 	out, _, err := runConfigCmd(t, file, "init")
 	require.NoError(t, err)
-	assert.Contains(t, out, file)
+	assert.Equal(t, "wrote config file "+strconv.Quote(file)+"\n", out)
 	content, err := os.ReadFile(file)
 	require.NoError(t, err)
 	assert.Equal(t, config.Minimal, string(content))

internal/app/cmd/daemon_test.go

@@ -145,7 +145,7 @@ func TestDaemonRetriesDeclareOutagesAndRemovesOnlyConsumedEphemeralRegistration(
 		{"ephemeral stopped during declare outage", true, true, connect.NewError(connect.CodeUnavailable, "bad gateway"), nil, false},
 	} {
 		t.Run(tc.name, func(t *testing.T) {
-			ctx, cancel := context.WithTimeout(t.Context(), 5*time.Second)
+			ctx, cancel := context.WithCancel(t.Context())
 			defer cancel()
 			service := &daemonTestService{declareErr: tc.declareErr, fetchErr: tc.fetchErr, beforeTask: tc.beforeTask, cancel: cancel}
 			rpcServer := connect.NewServer()

internal/app/cmd/register_test.go

@@ -183,6 +183,9 @@ func TestRegisterInputsAssignToNext(t *testing.T) {
 
 func TestInitInputs(t *testing.T) {
 	t.Setenv(registerTokenEnvVar, "")
+	missingTokenFile := filepath.Join(t.TempDir(), "missing-token")
+	_, readErr := os.ReadFile(missingTokenFile)
+	require.ErrorIs(t, readErr, os.ErrNotExist)
 	for _, tc := range []struct {
 		name, tokenFile, wantErr string
 		env                      *string
@@ -190,8 +193,8 @@ func TestInitInputs(t *testing.T) {
 		{name: "missing token", wantErr: "missing token, token-file argument, or GITEA_RUNNER_REGISTRATION_TOKEN environment variable"},
 		{name: "empty token", env: new(""), wantErr: "missing token, token-file argument, or GITEA_RUNNER_REGISTRATION_TOKEN environment variable"},
 		{
-			name: "invalid token file", tokenFile: "/tmp/nonexistent", env: new("from-env"),
-			wantErr: "cannot read the token file: /tmp/nonexistent, open /tmp/nonexistent: no such file or directory",
+			name: "invalid token file", tokenFile: missingTokenFile, env: new("from-env"),
+			wantErr: "cannot read the token file: " + missingTokenFile + ", " + readErr.Error(),
 		},
 	} {
 		t.Run(tc.name, func(t *testing.T) {

internal/app/cmd/service_others.go

@@ -0,0 +1,12 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+//go:build !windows
+
+package cmd
+
+import "context"
+
+func runService(ctx context.Context, run func(context.Context) error) error {
+	return run(ctx)
+}

internal/app/cmd/service_windows.go

@@ -0,0 +1,107 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package cmd
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"time"
+
+	"gitea.com/gitea/runner/act/common/logging"
+
+	"golang.org/x/sys/windows/svc"
+)
+
+func runService(ctx context.Context, run func(context.Context) error) error {
+	isService, err := svc.IsWindowsService()
+	if err != nil {
+		return fmt.Errorf("detect Windows service: %w", err)
+	}
+	if !isService {
+		return run(ctx)
+	}
+
+	handler := &daemonService{ctx: ctx, run: func(ctx context.Context) error {
+		executable, err := os.Executable()
+		if err != nil {
+			return err
+		}
+		if err := os.Chdir(filepath.Dir(executable)); err != nil {
+			return err
+		}
+		logFile, err := os.OpenFile("gitea-runner.log", os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0o600)
+		if err != nil {
+			return fmt.Errorf("open service log: %w", err)
+		}
+		defer func() { _ = logFile.Close() }()
+		previousOutput := logging.Output()
+		logging.SetOutput(logFile)
+		defer logging.SetOutput(previousOutput)
+		err = run(ctx)
+		if errors.Is(err, context.Canceled) && ctx.Err() != nil {
+			return nil
+		}
+		if err != nil {
+			logging.WithError(err).Error("runner daemon failed")
+		}
+		return err
+	}}
+	if err := svc.Run("", handler); err != nil { // SCM supplies the name for an own-process service.
+		return fmt.Errorf("run Windows service: %w", err)
+	}
+	return handler.err
+}
+
+type daemonService struct {
+	ctx context.Context
+	run func(context.Context) error
+	err error
+}
+
+func (s *daemonService) Execute(_args []string, requests <-chan svc.ChangeRequest, changes chan<- svc.Status) (bool, uint32) {
+	ticker := time.NewTicker(time.Second)
+	defer ticker.Stop()
+	return s.execute(requests, changes, ticker.C)
+}
+
+func (s *daemonService) execute(requests <-chan svc.ChangeRequest, changes chan<- svc.Status, ticks <-chan time.Time) (bool, uint32) {
+	changes <- svc.Status{State: svc.StartPending}
+	ctx, cancel := context.WithCancel(s.ctx)
+	defer cancel()
+	done := make(chan error, 1)
+	go func() { done <- s.run(ctx) }()
+	status := svc.Status{State: svc.Running, Accepts: svc.AcceptStop | svc.AcceptShutdown | svc.AcceptPreShutdown}
+	changes <- status
+	for {
+		select {
+		case s.err = <-done:
+			if status.State != svc.StopPending {
+				changes <- svc.Status{State: svc.StopPending}
+			}
+			if s.err != nil {
+				return true, 1
+			}
+			return false, 0
+		case <-ticks:
+			if status.State == svc.StopPending {
+				status.CheckPoint++
+				changes <- status
+			}
+		case request := <-requests:
+			switch request.Cmd {
+			case svc.Interrogate:
+				changes <- status
+			case svc.Stop, svc.Shutdown, svc.PreShutdown:
+				if status.State != svc.StopPending {
+					status = svc.Status{State: svc.StopPending, CheckPoint: 1, WaitHint: 10000}
+					changes <- status
+					cancel()
+				}
+			}
+		}
+	}
+}

internal/app/cmd/service_windows_test.go

@@ -0,0 +1,216 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package cmd
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"gitea.com/gitea/runner/act/common/logging"
+	"gitea.com/gitea/runner/internal/pkg/config"
+
+	"github.com/stretchr/testify/require"
+	"golang.org/x/sys/windows"
+	"golang.org/x/sys/windows/svc"
+	"golang.org/x/sys/windows/svc/mgr"
+)
+
+type serviceExit struct {
+	specific bool
+	code     uint32
+}
+
+func receiveServiceValue[T any](ctx context.Context, t *testing.T, values <-chan T) T {
+	t.Helper()
+	select {
+	case value := <-values:
+		return value
+	case <-ctx.Done():
+		t.Fatal(ctx.Err())
+		var zero T
+		return zero
+	}
+}
+
+func TestDaemonServiceControl(t *testing.T) {
+	for _, command := range []svc.Cmd{svc.Stop, svc.Shutdown, svc.PreShutdown} {
+		t.Run(fmt.Sprint(command), func(t *testing.T) {
+			ctx, cancel := context.WithTimeout(t.Context(), 10*time.Second)
+			defer cancel()
+			release, finish := context.WithCancel(ctx)
+			defer finish()
+			cancelled := make(chan struct{})
+			requests := make(chan svc.ChangeRequest, 1)
+			ticks := make(chan time.Time)
+			changes := make(chan svc.Status, 8)
+			done := make(chan serviceExit, 1)
+			handler := &daemonService{ctx: ctx, run: func(ctx context.Context) error {
+				<-ctx.Done()
+				close(cancelled)
+				<-release.Done()
+				return nil
+			}}
+			go func() {
+				specific, code := handler.execute(requests, changes, ticks)
+				done <- serviceExit{specific, code}
+			}()
+
+			require.Equal(t, svc.Status{State: svc.StartPending}, receiveServiceValue(ctx, t, changes))
+			running := svc.Status{State: svc.Running, Accepts: svc.AcceptStop | svc.AcceptShutdown | svc.AcceptPreShutdown}
+			require.Equal(t, running, receiveServiceValue(ctx, t, changes))
+			requests <- svc.ChangeRequest{Cmd: svc.Interrogate}
+			require.Equal(t, running, receiveServiceValue(ctx, t, changes))
+			requests <- svc.ChangeRequest{Cmd: command}
+			stopping := svc.Status{State: svc.StopPending, CheckPoint: 1, WaitHint: 10000}
+			require.Equal(t, stopping, receiveServiceValue(ctx, t, changes))
+			receiveServiceValue(ctx, t, cancelled)
+			for range 2 {
+				select {
+				case ticks <- time.Time{}:
+				case <-ctx.Done():
+					t.Fatal(ctx.Err())
+				}
+				stopping.CheckPoint++
+				require.Equal(t, stopping, receiveServiceValue(ctx, t, changes))
+			}
+			requests <- svc.ChangeRequest{Cmd: command}
+			requests <- svc.ChangeRequest{Cmd: svc.Interrogate}
+			require.Equal(t, stopping, receiveServiceValue(ctx, t, changes))
+			finish()
+			require.Equal(t, serviceExit{}, receiveServiceValue(ctx, t, done))
+			require.NoError(t, handler.err)
+		})
+	}
+}
+
+func TestDaemonServiceExit(t *testing.T) {
+	for _, daemonErr := range []error{nil, errors.New("daemon failed")} {
+		t.Run(fmt.Sprint(daemonErr), func(t *testing.T) {
+			ctx, cancel := context.WithTimeout(t.Context(), 10*time.Second)
+			defer cancel()
+			changes := make(chan svc.Status, 3)
+			done := make(chan serviceExit, 1)
+			handler := &daemonService{ctx: ctx, run: func(context.Context) error { return daemonErr }}
+			go func() {
+				specific, code := handler.Execute(nil, nil, changes)
+				done <- serviceExit{specific, code}
+			}()
+			require.Equal(t, svc.StartPending, receiveServiceValue(ctx, t, changes).State)
+			require.Equal(t, svc.Running, receiveServiceValue(ctx, t, changes).State)
+			require.Equal(t, svc.Status{State: svc.StopPending}, receiveServiceValue(ctx, t, changes))
+			if daemonErr == nil {
+				require.Equal(t, serviceExit{}, receiveServiceValue(ctx, t, done))
+			} else {
+				require.Equal(t, serviceExit{true, 1}, receiveServiceValue(ctx, t, done))
+			}
+			require.Equal(t, daemonErr, handler.err)
+		})
+	}
+}
+
+func waitForServiceState(t *testing.T, service *mgr.Service, state svc.State) svc.Status {
+	t.Helper()
+	ctx, cancel := context.WithTimeout(context.WithoutCancel(t.Context()), 20*time.Second)
+	defer cancel()
+	ticker := time.NewTicker(10 * time.Millisecond)
+	defer ticker.Stop()
+	for {
+		status, err := service.Query()
+		require.NoError(t, err)
+		if status.State == state {
+			return status
+		}
+		if state == svc.Running && status.State == svc.Stopped {
+			t.Fatalf("service stopped before running: %+v", status)
+		}
+		select {
+		case <-ticker.C:
+		case <-ctx.Done():
+			t.Fatalf("waiting for service state %d, last status: %+v", state, status)
+		}
+	}
+}
+
+func TestWindowsService(t *testing.T) {
+	isService, err := svc.IsWindowsService()
+	require.NoError(t, err)
+	if isService {
+		require.NoError(t, runService(t.Context(), func(ctx context.Context) error {
+			initLogging(&config.Config{})
+			logging.Info("service started")
+			<-ctx.Done()
+			logging.Info("service stopped")
+			return nil
+		}))
+		return
+	}
+	if !windows.GetCurrentProcessToken().IsElevated() {
+		t.Skip("Windows service test requires elevation")
+	}
+
+	executable, err := os.Executable()
+	require.NoError(t, err)
+	binary, err := os.ReadFile(executable)
+	require.NoError(t, err)
+	directory := t.TempDir()
+	serviceExecutable := filepath.Join(directory, "runner service.test.exe")
+	require.NoError(t, os.WriteFile(serviceExecutable, binary, 0o600))
+	manager, err := mgr.Connect()
+	require.NoError(t, err)
+	t.Cleanup(func() { require.NoError(t, manager.Disconnect()) })
+	service, err := manager.CreateService(
+		fmt.Sprintf("gitea-runner-test-%d-%d", os.Getpid(), time.Now().UnixNano()),
+		serviceExecutable, mgr.Config{StartType: mgr.StartManual}, "-test.run=^TestWindowsService$", "-test.timeout=1m",
+	)
+	require.NoError(t, err)
+	t.Cleanup(func() { require.NoError(t, service.Close()) })
+	t.Cleanup(func() { require.NoError(t, service.Delete()) })
+	var process windows.Handle
+	t.Cleanup(func() {
+		if process != 0 {
+			require.NoError(t, windows.CloseHandle(process))
+		}
+	})
+	t.Cleanup(func() {
+		if process == 0 {
+			return
+		}
+		result, err := windows.WaitForSingleObject(process, 20000)
+		require.NoError(t, err)
+		if result == uint32(windows.WAIT_TIMEOUT) {
+			t.Error("service process did not exit after stopping")
+			require.NoError(t, windows.TerminateProcess(process, 1))
+			result, err = windows.WaitForSingleObject(process, 20000)
+			require.NoError(t, err)
+		}
+		require.Equal(t, uint32(windows.WAIT_OBJECT_0), result)
+	})
+	t.Cleanup(func() {
+		status, err := service.Query()
+		require.NoError(t, err)
+		if status.State != svc.Stopped {
+			_, err := service.Control(svc.Stop)
+			require.NoError(t, err)
+			waitForServiceState(t, service, svc.Stopped)
+		}
+	})
+	require.NoError(t, service.Start())
+	running := waitForServiceState(t, service, svc.Running)
+	process, err = windows.OpenProcess(windows.SYNCHRONIZE|windows.PROCESS_TERMINATE, false, running.ProcessId)
+	require.NoError(t, err)
+	_, err = service.Control(svc.Stop)
+	require.NoError(t, err)
+	stopped := waitForServiceState(t, service, svc.Stopped)
+	require.Zero(t, stopped.Win32ExitCode)
+	require.Zero(t, stopped.ServiceSpecificExitCode)
+	log, err := os.ReadFile(filepath.Join(directory, "gitea-runner.log"))
+	require.NoError(t, err)
+	require.Contains(t, string(log), "service started")
+	require.Contains(t, string(log), "service stopped")
+}