This project automates the provisioning of a GitLab Runner inside a lightweight Ubuntu VM using Multipass. It's fast, reproducible, and deployable with a single command.
- 🔄 One-command GitLab runner deployment with
start.sh - 📦 Auto-provisioned runner using cloud-init
- 🐧 Works on Windows, macOS, and Linux
- 🏷️ Supports GitLab runner tags (e.g.
cypress) - 🔁 Easily rebuild, restart, or debug your runner VM
- Multipass (see install instructions below)
- A GitLab registration token
- Git Bash (for Windows users)
-
Install Chocolatey:
Set-ExecutionPolicy Bypass -Scope Process -Force; ` [System.Net.ServicePointManager]::SecurityProtocol = ` [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; ` iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))
-
Install Multipass:
choco install multipass
-
Run:
./start.sh
🧠 Use Git Bash for running scripts on Windows.
-
Install Homebrew:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" -
Install Multipass:
brew install --cask multipass
-
Run:
./start.sh
-
Install Snap:
sudo apt update sudo apt install snapd
-
Install Multipass:
sudo snap install multipass
-
Run:
./start.sh
Copy and configure .env using the included example:
📄 See .env.example for all options.
Start or rebuild the VM:
./start.sh # spin up or resume
./rebuild.sh # destroy and recreateGet a shell inside the VM:
multipass shell $VM_NAMEThis repo is especially useful for jobs that need:
- 🧪 Cypress E2E Testing
- Use tag
cypressin your GitLab CI job - Offload Chrome/Electron tests to local VM
- Use tag
Other potential use cases:
- 🐳 Docker-based builds (Node, Python, Go, etc.)
- 🧬 Containerized integration tests
- 📸 Visual regression testing (e.g. Percy, Playwright)
- 📦 Packaging or CI caching in self-contained environments
Feel free to fork, extend, or open PRs — this project welcomes improvements!