GitLab Runner Scripts Reference

Last Updated: 2025-01-XX
Location: $LLM_ROOT/scripts/

Complete reference for all GitLab runner management scripts.

Quick Reference

Script Details

setup-local-runners.sh

Purpose: Register GitLab runners with proper tags

Usage:

# Option 1: Direct token
export RUNNER_TOKEN="<RUNNER_REGISTRATION_TOKEN>"
./scripts/setup-local-runners.sh

# Option 2: Via API
export GITLAB_TOKEN="glpat-xxx"
./scripts/setup-local-runners.sh

What it does:

• Auto-detects platform (macOS/Linux, ARM64/x86_64)
• Registers 5 runners:
  • docker-runner (generic Docker jobs)
  • npm-runner (NPM/TypeScript projects)
  • drupal-module-runner (Drupal/PHP projects)
  • drupal-recipe-runner (Drupal recipes)
  • python-runner (Python projects)
• Uses proper tags matching the tag system

Output: Runners registered in ~/.gitlab-runner/config.toml

---

check-runner-status.sh

Purpose: Comprehensive status check

Usage:

# With API token (shows GitLab status)
export GITLAB_TOKEN="glpat-xxx"
./scripts/check-runner-status.sh

# Without API token (local only)
./scripts/check-runner-status.sh

What it does:

• Lists registered local runners
• Verifies runner connectivity
• Checks GitLab API for group runners
• Shows configuration details

Output: Status report with runner details

---

quick-start-runners.sh

Purpose: One-command complete setup

Usage:

export RUNNER_TOKEN="<RUNNER_REGISTRATION_TOKEN>"
./scripts/quick-start-runners.sh

What it does:

• Installs gitlab-runner if needed (macOS via Homebrew)
• Runs setup script to register runners
• Starts runners as daemon
• Verifies setup

Output: Complete setup with runners running

---

verify-runner-tags.sh

Purpose: Verify runner tags match expected configuration

Usage:

./scripts/verify-runner-tags.sh

What it does:

• Reads ~/.gitlab-runner/config.toml
• Checks each runner's tags
• Verifies tags match expected values:
  • npm-runner: npm-package,typescript,docker,local
  • drupal-module-runner: drupal-module,docker,local
  • docker-runner: docker,local
• Reports any mismatches

Output: Verification report ( or for each runner)

Exit Code: 0 if all tags match, 1 if any issues found

---

update-runner-tags.sh

Purpose: Update runner tags in config.toml

Usage:

./scripts/update-runner-tags.sh

What it does:

• Creates backup of config.toml
• Auto-detects platform tags
• Updates tags for all runners:
  • npm-runner: adds platform tags
  • drupal-module-runner: adds platform tags
  • docker-runner: adds platform tags
• Preserves existing configuration

Output: Updated config with backup saved

Note: Restart runners after updating: gitlab-runner restart

---

runner-dashboard.sh

Purpose: Comprehensive dashboard

Usage:

# With API token (full dashboard)
export GITLAB_TOKEN="glpat-xxx"
./scripts/runner-dashboard.sh

# Without API token (local only)
./scripts/runner-dashboard.sh

What it does:

• Shows local runner status
• Shows GitLab API status (if token provided)
• Shows registration token status
• Provides quick actions menu
• Links to GitLab UI

Output: Formatted dashboard with all information

---

Common Workflows

Setting Up New Computer

# 1. Get registration token
export RUNNER_TOKEN="<RUNNER_REGISTRATION_TOKEN>"

# 2. Run quick start (installs, registers, starts)
./scripts/quick-start-runners.sh

# 3. Verify
./scripts/verify-runner-tags.sh

Verifying Existing Setup

# 1. Check status
./scripts/check-runner-status.sh

# 2. Verify tags
./scripts/verify-runner-tags.sh

# 3. View dashboard
export GITLAB_TOKEN="glpat-xxx"
./scripts/runner-dashboard.sh

Updating Tags

# 1. Update tags
./scripts/update-runner-tags.sh

# 2. Verify changes
./scripts/verify-runner-tags.sh

# 3. Restart runners
gitlab-runner restart

Troubleshooting

# 1. Check status
./scripts/check-runner-status.sh

# 2. Verify tags
./scripts/verify-runner-tags.sh

# 3. View logs
tail -f ~/.gitlab-runner/logs/gitlab-runner.log

# 4. Restart if needed
gitlab-runner restart

Environment Variables

Configuration Files

• Runner Config: ~/.gitlab-runner/config.toml
• Logs: ~/.gitlab-runner/logs/gitlab-runner.log
• Backups: ~/.gitlab-runner/config.toml.backup.*

Related Documentation

• SETUP-SECOND-COMPUTER.md - Setup guide
• LOCAL-RUNNERS.md - Complete guide
• FINAL-RUNNER-TAGS.md - Tag reference
• RUNNER-TOKEN.md - Token management