ci: run race tests through a flake check

.github/workflows/nix-checks.yml

@@ -37,6 +37,16 @@ jobs:
       - name: gotest
         run: nix build -L .#checks.x86_64-linux.gotest
 
+  gorace:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: NixOS/nix-installer-action@62c1943b776c509394b550f3f983adc14e9212d6 # main
+      - uses: Mic92/hestia@dfed9ced335d28978ba74e513939a10db1f71025 # v3.1.0
+      - name: gorace
+        run: nix build -L .#checks.x86_64-linux.gorace
+
   golangci-lint:
     runs-on: ubuntu-latest
     steps:

AGENTS.md

@@ -82,7 +82,10 @@ make clean           # remove build artefacts
 
 # Direct go test invocations
 go test ./...
-go test -race ./...
+CGO_ENABLED=1 go test -race ./...
+
+# CI race check
+nix build -L .#checks.x86_64-linux.gorace
 
 # Integration tests — read cmd/hi/README.md first
 go run ./cmd/hi doctor
@@ -96,6 +99,9 @@ go run ./tools/bump verify   # do the pins still agree
 Go 1.27.3 minimum (per `go.mod:3`). `nix develop` pins the exact toolchain
 used in CI.
 
+The dev shell exports `CGO_ENABLED=0`; `-race` needs cgo, and CI runs the
+`gorace` flake check (package selection in `flake.nix`).
+
 ## Pre-Commit with prek
 
 `prek` installs git hooks that run the same checks as CI.

flake.nix

@@ -199,7 +199,7 @@
           # from the test set but kept in source so cmd/hi and friends still
           # compile. Pure integration helper tests remain included.
           # TestPostgres* needs a server (the SQLite equivalents still
-          # run). CGO off matches the build.
+          # run). This check keeps CGO off; gorace below enables it for tests.
           gotest = fc.goTest (
             common
             // {
@@ -212,6 +212,21 @@
             }
           );
 
+          # -race needs cgo; release build and dev shell stay CGO-free.
+          # Test hscontrol recursively; servertest runs in its own workflow, without -race.
+          gorace = fc.goTest (
+            common
+            // {
+              name = "headscale-gorace";
+              goRace = true;
+              testEnv = "export CGO_ENABLED=1";
+              testFlags = [ "-p=2" ];
+              goSkip = [ "TestPostgres" ];
+              testPackages = "./hscontrol/...";
+              testExclude = [ "/hscontrol/servertest" ];
+            }
+          );
+
           # Full-tree golangci-lint (gofumpt, gci, etc.); uses the overlay's
           # golangci-lint built against the pinned Go.
           golangci-lint = fc.goLint common;