doc update

docs/gitlab-runner-nix-setup.md

@@ -27,6 +27,15 @@ Add to `/etc/nixos/configuration.nix`:
   # Install Docker
   virtualisation.docker.enable = true;
 
+  # Configure gitlab-runner user and group
+  users.users.gitlab-runner = {
+    isSystemUser = true;
+    group = "gitlab-runner";
+    extraGroups = [ "docker" ];
+  };
+
+  users.groups.gitlab-runner = {};
+
   # Configure GitLab Runner
   services.gitlab-runner = {
     enable = true;
@@ -46,9 +55,6 @@ Add to `/etc/nixos/configuration.nix`:
       };
     };
   };
-
-  # Add gitlab-runner user to docker group
-  users.users.gitlab-runner.extraGroups = [ "docker" ];
 }
 ```
 
@@ -63,7 +69,40 @@ Create `/etc/gitlab-runner/nix-builder-registration`:
   executor = "docker"
 ```
 
-Get the registration token from: GitLab Project → Settings → CI/CD → Runners → New project runner
+**Getting the registration token**:
+
+#### New Token Workflow (Recommended - GitLab 16.0+):
+
+1. Go to: **Settings → CI/CD → Runners**
+2. Click: **New project runner**
+3. Configure runner settings:
+   - Tags: `nix`
+   - Run untagged jobs: **Uncheck**
+   - Description: "Nix Builder"
+4. Click **Create runner**
+5. Copy the token (starts with `glrt-`)
+
+Use simplified registration command:
+
+```bash
+sudo gitlab-runner register \
+  --url https://gitlab.com/ \
+  --token glrt-YOUR_TOKEN_HERE \
+  --executor docker \
+  --docker-image nixos/nix:latest \
+  --docker-privileged \
+  --docker-volumes /nix/store:/nix/store:ro \
+  --docker-volumes /nix/var/nix/db:/nix/var/nix/db:ro \
+  --docker-volumes /var/run/docker.sock:/var/run/docker.sock
+```
+
+**Important**: With new tokens, tags are configured in GitLab UI, not in the registration command.
+
+#### Legacy Token Workflow (GitLab <16.0):
+
+Get token from: **Settings → CI/CD → Runners → Project runners → Registration token**
+
+Registration config format is the same as above.
 
 ### 3. Apply Configuration
 
@@ -71,6 +110,28 @@ Get the registration token from: GitLab Project → Settings → CI/CD → Runne
 sudo nixos-rebuild switch
 ```
 
+This will:
+- Enable Nix flakes
+- Install and start Docker
+- Create gitlab-runner user and group
+- Configure and start GitLab Runner service
+- Add gitlab-runner to docker group
+
+### 4. Verify Setup
+
+```bash
+# Check services are running
+sudo systemctl status gitlab-runner
+sudo systemctl status docker
+
+# Verify gitlab-runner is in docker group
+id gitlab-runner
+# Should show: groups=... docker ...
+
+# Check runner registration
+sudo gitlab-runner list
+```
+
 ## Option 2: Standard Linux with Nix
 
 If you're using a standard Linux distribution with Nix installed:
@@ -95,10 +156,28 @@ sudo apt-get install gitlab-runner
 
 ### 2. Register Runner
 
+**With new GitLab tokens (16.0+)**:
+
 ```bash
 sudo gitlab-runner register \
   --url https://gitlab.com/ \
-  --token YOUR_RUNNER_REGISTRATION_TOKEN \
+  --token glrt-YOUR_TOKEN_HERE \
+  --executor docker \
+  --docker-image nixos/nix:latest \
+  --docker-privileged \
+  --docker-volumes /nix/store:/nix/store:ro \
+  --docker-volumes /nix/var/nix/db:/nix/var/nix/db:ro \
+  --docker-volumes /var/run/docker.sock:/var/run/docker.sock
+```
+
+Then configure tags in GitLab UI: **Settings → CI/CD → Runners → Edit → Add tag: `nix`**
+
+**With legacy tokens (<16.0)**:
+
+```bash
+sudo gitlab-runner register \
+  --url https://gitlab.com/ \
+  --token YOUR_REGISTRATION_TOKEN \
   --executor docker \
   --docker-image nixos/nix:latest \
   --docker-privileged \
@@ -219,6 +298,32 @@ Pushing to GitLab Container Registry...
 
 ## Troubleshooting
 
+### NixOS: User configuration errors
+
+**Error**: `users.users.gitlab-runner.isSystemUser` must be set
+
+**Fix**: Add user configuration to `/etc/nixos/configuration.nix`:
+
+```nix
+users.users.gitlab-runner = {
+  isSystemUser = true;
+  group = "gitlab-runner";
+  extraGroups = [ "docker" ];
+};
+
+users.groups.gitlab-runner = {};
+```
+
+### Runner registration with new tokens fails
+
+**Error**: `Runner configuration other than name and executor... is reserved`
+
+**Fix**: With new GitLab tokens (`glrt-*`), you cannot specify `--tag-list`, `--run-untagged`, etc. in the registration command. Configure these in GitLab UI instead:
+
+1. Register with minimal command (without `--tag-list`, `--run-untagged`)
+2. Go to GitLab UI: **Settings → CI/CD → Runners → Edit**
+3. Add tags and configure settings there
+
 ### Runner shows offline in GitLab
 
 **Check runner status**: