Setting Up GitLab Runners on Second Computer

Last Updated: 2025-01-XX
Status: Production Ready
Group: blueflyio/agent-platform

Complete guide for setting up GitLab runners on a second computer using the same tag system as the primary computer.

Prerequisites

Before starting, ensure you have:

GitLab Runner installed (see installation section below)
Docker or OrbStack running
Network access to GitLab.com
GitLab access token with admin/maintainer permissions for blueflyio/agent-platform group
Registration token from GitLab group settings

Step 1: Install GitLab Runner

macOS

# Install via Homebrew
brew install gitlab-runner

# Verify installation
gitlab-runner --version

Linux (Ubuntu/Debian)

# Download and install
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash
sudo apt-get install gitlab-runner

# Verify installation
gitlab-runner --version

Linux (RHEL/CentOS/Fedora)

# Download and install
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.rpm.sh" | sudo bash
sudo yum install gitlab-runner

# Verify installation
gitlab-runner --version

Windows

Download from: https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-windows-amd64.exe
Rename to gitlab-runner.exe
Place in a directory (e.g., C:\GitLab-Runner\)
Add to PATH or run from that directory

Step 2: Get Registration Token

Option A: Group-Level Runner (Recommended)

Go to: https://gitlab.com/groups/blueflyio/agent-platform/-/settings/ci_cd
Expand "Runners" section
Copy "Registration token" (starts with <RUNNER_REGISTRATION_TOKEN>...)

Option B: Use GitLab API

export GITLAB_TOKEN="glpat-your-personal-access-token"
curl -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "https://gitlab.com/api/v4/groups/blueflyio%2Fagent-platform" | jq -r '.runners_token'

Save the token:

export RUNNER_TOKEN="<RUNNER_REGISTRATION_TOKEN>"

Step 3: Determine Platform Tags

Based on your computer's platform, you'll use different platform tags:

Platform	Architecture	Platform Tags
macOS (Intel)	x86_64	`mac`, `x86_64`
macOS (Apple Silicon)	arm64	`mac`, `arm64`
Linux (Intel)	x86_64	`linux`, `x86_64`
Linux (ARM)	arm64	`linux`, `arm64`
Windows	x86_64	`windows`, `x86_64`

Note: Platform tags are optional but recommended for better job routing.

Step 4: Register Runners

1. Docker Runner (Generic)

macOS:

gitlab-runner register \
  --url https://gitlab.com/ \
  --registration-token $RUNNER_TOKEN \
  --executor docker \
  --docker-image docker:28-dind \
  --description "docker-runner - $(hostname)" \
  --tag-list "docker,local,mac,arm64" \
  --run-untagged=false \
  --locked=false

Linux:

gitlab-runner register \
  --url https://gitlab.com/ \
  --registration-token $RUNNER_TOKEN \
  --executor docker \
  --docker-image docker:28-dind \
  --description "docker-runner - $(hostname)" \
  --tag-list "docker,local,linux,x86_64" \
  --run-untagged=false \
  --locked=false

Windows:

gitlab-runner register `
  --url https://gitlab.com/ `
  --registration-token $env:RUNNER_TOKEN `
  --executor docker `
  --docker-image docker:28-dind `
  --description "docker-runner - $env:COMPUTERNAME" `
  --tag-list "docker,local,windows,x86_64" `
  --run-untagged=false `
  --locked=false

2. NPM Runner (Node.js/TypeScript)

macOS:

gitlab-runner register \
  --url https://gitlab.com/ \
  --registration-token $RUNNER_TOKEN \
  --executor docker \
  --docker-image node:20-alpine \
  --description "npm-runner - $(hostname)" \
  --tag-list "npm-package,typescript,docker,local,mac,arm64" \
  --run-untagged=false \
  --locked=false

Linux:

gitlab-runner register \
  --url https://gitlab.com/ \
  --registration-token $RUNNER_TOKEN \
  --executor docker \
  --docker-image node:20-alpine \
  --description "npm-runner - $(hostname)" \
  --tag-list "npm-package,typescript,docker,local,linux,x86_64" \
  --run-untagged=false \
  --locked=false

Windows:

gitlab-runner register `
  --url https://gitlab.com/ `
  --registration-token $env:RUNNER_TOKEN `
  --executor docker `
  --docker-image node:20-alpine `
  --description "npm-runner - $env:COMPUTERNAME" `
  --tag-list "npm-package,typescript,docker,local,windows,x86_64" `
  --run-untagged=false `
  --locked=false

3. Drupal Module Runner

macOS:

gitlab-runner register \
  --url https://gitlab.com/ \
  --registration-token $RUNNER_TOKEN \
  --executor docker \
  --docker-image ddev/ddev-webserver:latest \
  --description "drupal-module-runner - $(hostname)" \
  --tag-list "drupal-module,docker,local,mac,arm64" \
  --run-untagged=false \
  --locked=false

Linux:

gitlab-runner register \
  --url https://gitlab.com/ \
  --registration-token $RUNNER_TOKEN \
  --executor docker \
  --docker-image ddev/ddev-webserver:latest \
  --description "drupal-module-runner - $(hostname)" \
  --tag-list "drupal-module,docker,local,linux,x86_64" \
  --run-untagged=false \
  --locked=false

Windows:

gitlab-runner register `
  --url https://gitlab.com/ `
  --registration-token $env:RUNNER_TOKEN `
  --executor docker `
  --docker-image ddev/ddev-webserver:latest `
  --description "drupal-module-runner - $env:COMPUTERNAME" `
  --tag-list "drupal-module,docker,local,windows,x86_64" `
  --run-untagged=false `
  --locked=false

Step 5: Configure Docker Executor

After registration, edit the runner configuration file:

macOS/Linux: ~/.gitlab-runner/config.toml
Windows: C:\GitLab-Runner\config.toml

Standard Docker Configuration

concurrent = 4  # Adjust based on CPU cores (recommended: CPU cores - 1)
check_interval = 0

[[runners]]
  name = "docker-runner - $(hostname)"
  url = "https://gitlab.com"
  executor = "docker"
  [runners.docker]
    tls_verify = false
    image = "docker:28-dind"
    privileged = true
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    disable_cache = false
    volumes = [
      "/var/run/docker.sock:/var/run/docker.sock",  # Linux/macOS
      # For Windows: "//var/run/docker.sock:/var/run/docker.sock"
      "/tmp:/tmp",
      "/cache"
    ]
    network_mode = "bridge"
    shm_size = 0
  [runners.cache]
    Type = "local"
    Path = "/tmp/gitlab-runner-cache"
    Shared = true

Platform-Specific Docker Socket Paths

macOS (Docker Desktop):

volumes = [
  "/var/run/docker.sock:/var/run/docker.sock",
  "/tmp:/tmp",
  "/cache"
]

macOS (OrbStack):

volumes = [
  "~/.orbstack/run/docker.sock:/var/run/docker.sock",
  "/tmp:/tmp",
  "/cache"
]

Linux:

volumes = [
  "/var/run/docker.sock:/var/run/docker.sock",
  "/tmp:/tmp",
  "/cache"
]

Windows (Docker Desktop):

volumes = [
  "//var/run/docker.sock:/var/run/docker.sock",
  "C:/tmp:/tmp",
  "C:/cache:/cache"
]

Step 6: Start Runners

macOS/Linux

# Start as daemon (background, recommended)
gitlab-runner run --daemon

# Or start in foreground for testing
gitlab-runner run

# Verify runners are running
gitlab-runner verify
gitlab-runner list

Windows

As Service (Recommended):

# Install as Windows service
cd C:\GitLab-Runner
.\gitlab-runner.exe install
.\gitlab-runner.exe start

# Verify
.\gitlab-runner.exe verify
.\gitlab-runner.exe list

As Background Process:

# Run in background
Start-Process -FilePath "C:\GitLab-Runner\gitlab-runner.exe" -ArgumentList "run" -WindowStyle Hidden

Step 7: Verify Setup

Check Runner Status

# List all registered runners
gitlab-runner list

# Verify connectivity
gitlab-runner verify

# Check runner logs
# macOS/Linux:
tail -f ~/.gitlab-runner/logs/gitlab-runner.log

# Windows:
Get-Content C:\GitLab-Runner\logs\gitlab-runner.log -Tail 50 -Wait

Verify in GitLab UI

Go to: https://gitlab.com/groups/blueflyio/agent-platform/-/settings/ci_cd
Expand "Runners" section
Verify all three runners show as "Online" and "Active"
Check that tags match what you registered

Test with a Pipeline

Create a test merge request or push to a branch
Check pipeline runs on your local runner:
- Go to GitLab CI/CD Pipelines
- Click on pipeline
- Verify "Runner" shows your runner name (e.g., "docker-runner - hostname")
- Check job logs for runner identification

Tag System Reference

Standard Tags (Always Required)

Every runner must have:

docker - Required for Docker executor
local - Identifies self-hosted runners

Project-Type Tags

Runner	Required Tags	Purpose
docker-runner	`docker, local, [platform]`	Generic Docker jobs
npm-runner	`npm-package, typescript, docker, local, [platform]`	NPM/TypeScript projects
drupal-module-runner	`drupal-module, docker, local, [platform]`	Drupal/PHP projects

Platform Tags

Add based on your system:

mac, arm64 - macOS Apple Silicon
mac, x86_64 - macOS Intel
linux, x86_64 - Linux Intel
linux, arm64 - Linux ARM
windows, x86_64 - Windows

Note: Platform tags are optional but help with job routing and identification.

Performance Tuning

Concurrent Jobs

Edit config.toml:

concurrent = 4  # Adjust based on CPU cores

Recommendations:

4-core CPU: concurrent = 3
6-core CPU: concurrent = 4-5
8-core CPU: concurrent = 6-7
10+ core CPU: concurrent = 8-10

Monitor CPU/memory usage and adjust accordingly.

Resource Limits

[runners.docker]
  memory = "4g"  # Limit memory per job
  cpus = "2"     # Limit CPU per job

Cache Configuration

[runners.cache]
  Type = "local"
  Path = "/tmp/gitlab-runner-cache"  # Linux/macOS
  # Path = "C:/cache"  # Windows
  Shared = true
  MaxUploadedArchiveSize = 0  # Unlimited

Troubleshooting

Runner Not Picking Up Jobs

Check tag match: Job tags must be subset of runner tags
Check runner status: gitlab-runner verify
Check GitLab UI: Verify runner is "online" and "active"
Check logs: Review runner logs for errors

Docker Issues

Test Docker access:

docker ps
docker run hello-world

Check Docker socket:

# Linux/macOS
ls -la /var/run/docker.sock

# macOS OrbStack
ls -la ~/.orbstack/run/docker.sock

# Windows
Test-Path //var/run/docker.sock

Test Docker-in-Docker:

docker run --privileged docker:28-dind docker ps

Permission Issues

macOS/Linux:

# Ensure user is in docker group
sudo usermod -aG docker $USER
# Log out and back in for changes to take effect

Windows:

Ensure Docker Desktop is running
Check Docker Desktop settings General "Use the WSL 2 based engine" (if using WSL)

Network Issues

# Test GitLab connectivity
curl -I https://gitlab.com

# Test runner can reach GitLab
gitlab-runner verify

Security Considerations

Runner Tokens: Store securely, rotate regularly (every 90 days)
Privileged Mode: Only enable when needed (Docker-in-Docker)
Resource Limits: Set CPU/memory limits to prevent resource exhaustion
Access Control: Use protected branches and tags
Token Rotation: Rotate registration tokens quarterly

Maintenance

Update Runner

macOS:

brew upgrade gitlab-runner
gitlab-runner stop
gitlab-runner start

Linux:

sudo apt-get update && sudo apt-get upgrade gitlab-runner
# or
sudo yum update gitlab-runner

sudo gitlab-runner stop
sudo gitlab-runner start

Windows:

Download latest from GitLab
Stop service: gitlab-runner.exe stop
Replace executable
Start service: gitlab-runner.exe start

Clean Up

# Remove old cache
rm -rf /tmp/gitlab-runner-cache/*  # Linux/macOS
# or
Remove-Item -Recurse -Force C:\cache\*  # Windows

# Clean Docker images
docker system prune -a --filter "until=168h"  # Keep images from last week

Best Practices

Use same tag system as primary computer for consistency
Include platform tags for better identification
Monitor resource usage and adjust concurrent jobs
Clean cache regularly to prevent disk space issues
Rotate tokens quarterly for security
Use runner-selector component in CI files for automatic routing
Enable fallback to shared runners for reliability

FINAL-RUNNER-TAGS.md - Complete tag reference
LOCAL-RUNNERS.md - Complete setup guide
RUNNER-SETUP-SUMMARY.md - Setup summary

Quick Reference

Registration Commands (macOS Apple Silicon)

export RUNNER_TOKEN="your-token-here"

# Docker runner
gitlab-runner register --url https://gitlab.com/ --registration-token $RUNNER_TOKEN --executor docker --docker-image docker:28-dind --description "docker-runner - $(hostname)" --tag-list "docker,local,mac,arm64" --run-untagged=false --locked=false

# NPM runner
gitlab-runner register --url https://gitlab.com/ --registration-token $RUNNER_TOKEN --executor docker --docker-image node:20-alpine --description "npm-runner - $(hostname)" --tag-list "npm-package,typescript,docker,local,mac,arm64" --run-untagged=false --locked=false

# Drupal runner
gitlab-runner register --url https://gitlab.com/ --registration-token $RUNNER_TOKEN --executor docker --docker-image ddev/ddev-webserver:latest --description "drupal-module-runner - $(hostname)" --tag-list "drupal-module,docker,local,mac,arm64" --run-untagged=false --locked=false

Start Runners

gitlab-runner run --daemon
gitlab-runner verify
gitlab-runner list

Setting Up GitLab Runners on Second Computer

Setting Up GitLab Runners on Second Computer

Prerequisites

Step 1: Install GitLab Runner

macOS

Linux (Ubuntu/Debian)

Linux (RHEL/CentOS/Fedora)

Windows

Step 2: Get Registration Token

Step 3: Determine Platform Tags

Step 4: Register Runners

1. Docker Runner (Generic)

2. NPM Runner (Node.js/TypeScript)

3. Drupal Module Runner

Step 5: Configure Docker Executor

Standard Docker Configuration

Platform-Specific Docker Socket Paths

Step 6: Start Runners

macOS/Linux

Windows

Step 7: Verify Setup

Check Runner Status

Verify in GitLab UI

Test with a Pipeline

Tag System Reference

Standard Tags (Always Required)

Project-Type Tags

Platform Tags

Performance Tuning

Concurrent Jobs

Resource Limits

Cache Configuration

Troubleshooting

Runner Not Picking Up Jobs

Docker Issues

Permission Issues

Network Issues

Security Considerations

Maintenance

Update Runner

Clean Up

Best Practices

Related Documentation

Quick Reference

Registration Commands (macOS Apple Silicon)

Start Runners