1. 100% Drop-in GitLab Runner Compatibility
Saur is a pure Go single-binary replacement for gitlab-runner. Replace the binary on any server without modifying GitLab projects, CI/CD YAML files, or registration workflows.
Supports gitlab-runner register, run, and verify with identical arguments.
Automatically parses existing /etc/gitlab-runner/config.toml without conversion.
Unlocks 0 MB idle memory, <10ms cold start, direct S3 offload, and WASI.
| Official gitlab-runner CLI | Saur Equivalent | Compatibility |
|---|---|---|
| gitlab-runner run / run-single | saur run / saur run-single | 100% Drop-in |
| gitlab-runner register | saur register | 100% Drop-in |
| gitlab-runner verify / list | saur verify / saur list | 100% Drop-in |
| --url, -u / --token, -t | --url, -u / --token, -t | Identical |
| Multi-Runner config.toml ([[runners]]) | Multi-Runner Supervisor (All Online) | 100% Concurrent |
| File-Type Variables & Secrets | Zero-Disk RAM (/dev/shm) + ZeroWipe | Superior Security |
2. CLI Commands & Quick Start
Core commands to install, register, and manage the Saur runner.
# 1. Install Saur (Linux / macOS / Alpine) $ curl -fsSL https://saur.run/install.sh | bash # 2. Register Runner (Paste directly from GitLab UI) $ gitlab-runner register --url="https://gitlab.com" --token="glrt-YOUR_RUNNER_TOKEN" # 3. Verify Status & Start $ saur status $ saur run
3. Configuration & Environment Variables
Saur can be configured via CLI flags, environment variables, .env files, or standard /etc/gitlab-runner/config.toml.
| Environment Variable | CLI Flag | Default | Description |
|---|---|---|---|
| GITLAB_RUNNER_TOKEN | --token, -t | — | Runner Token (glrt-...) or Access Token (glpat-...) |
| GITLAB_URL | --url, -u | https://gitlab.com | GitLab instance endpoint |
| RUNNER_TAGS / RUNNER_TAG_LIST | --tags, --tag-list | saur.run,spot | Comma-separated runner tags |
| RUNNER_EXECUTOR / EXECUTOR | --executor | shell | Engine: shell (host) or wasi (WASM Sandbox) |
| RUNNER_CONCURRENT / CONCURRENT | --concurrent | 1 | Max concurrent jobs |
| LISTEN_ADDR / PORT | --listen | :8081 (or $PORT) | Healthcheck & Webhook listen address |
| SAUR_WEBHOOK_SECRET | --webhook-secret | — | Secret token for GitLab webhook validation |
| SAUR_IDLE_TIMEOUT | --idle-timeout | 3m | Idle duration before Scale-to-Zero hibernation |
concurrent = 4 check_interval = 0 [[runners]] name = "saur-node-01" url = "https://gitlab.com" token = "glrt-YOUR_RUNNER_TOKEN" executor = "shell" scale_to_zero = true idle_timeout = "30s" wasi_enabled = true
4. Scale-to-Zero & Cloud-Native Architecture
How Saur frees 100% of memory during idle standby and operates seamlessly in auto-scaled Spot VM clusters.
When the job queue is empty, Saur releases all process heaps and enters 0 MB idle standby. Upon new job arrival via HTTP long-poll, Saur resumes execution in <10 ms.
Automatically generates unique node IDs based on instance metadata and deregisters gracefully on SIGTERM during VM teardown.
Docker & Container Deployments (2 Operating Modes)
One single ultra-light OCI container (Alpine · ~30 MB) supporting two execution modes: 100% GitLab Runner Daemon mode and Event-Driven Serverless mode.
Runs continuously in Docker, Podman, or Kubernetes. Long-polls GitLab API with Level 1 Scale-to-Zero memory hibernation.
$ docker run -d --name saur-runner \
-v /var/run/docker.sock:/var/run/docker.sock \
-e GITLAB_URL=https://gitlab.com \
-e GITLAB_RUNNER_TOKEN=glrt-YOUR_RUNNER_TOKEN \
registry.gitlab.com/saur.run/saur:latest
Event-driven PUSH mode. Cold-starts in ~500ms on GitLab webhook and scales down to 0 instances ($0.00 idle cost).
$ gcloud run deploy saur-runner \
--image=registry.gitlab.com/saur.run/saur:latest \
--port=8080 --min-instances=0 \
--set-env-vars="GITLAB_URL=https://gitlab.com,GITLAB_RUNNER_TOKEN=glrt-YOUR_TOKEN" \
--allow-unauthenticated
$ docker run -d --name saur-test -p 8080:8080 -e K_SERVICE=local-test -e SAUR_WEBHOOK_SECRET=my-secret registry.gitlab.com/saur.run/saur:latest
# Health Check (Expect 200 OK)
$ curl -fsSL http://localhost:8080/healthz
# Simulate GitLab Pipeline Webhook (Expect 200 OK {"action":"job_requested"})
$ curl -fsSL -X POST http://localhost:8080/ \
-H "Content-Type: application/json" \
-H "X-Gitlab-Token: my-secret" \
-d '{"object_kind":"pipeline","object_attributes":{"id":1,"status":"pending"}}'
$ docker stats saur-test --no-stream # Memory: ~7.8 MiB, CPU: 0.02% $ docker rm -f saur-test
5. Runner Status Web Component
Embed live telemetry and pipeline health badges into any web dashboard in 1 line of HTML.
6. OpenAPI 3.0 Contract
Complete machine-readable OpenAPI 3.0 specification covering runner registration, health endpoints, job polling, and real-time SSE metrics.
7. Official GitLab Runner Feature Matrix & Roadmap
Comprehensive technical breakdown of implemented features, planned capabilities, and permanent architectural decisions.
Job long-polling, 18+ declared features, real-time trace streaming, and auto token rotation.